GSMA OGW Product WS - Administrative/Postal Codes formal request

[jgarciahospital]

Problem description Formal inclusion of the GSMA OGW Product WS request to include Postal/administrative Codes support for location verification services (basic API and geofencing/subscription API)

Possible evolution API input includes not only center+radious or other geographical figure, but also administrative zones

Alternative solution N/A

Additional context More details included in the formal request file, attached Camara Submission - DevLocVerifAdminCode v2.docx

[jlurien]

There is some previous work, started as issue #39, that was specifically focused on Postal Codes. Now, the requirement is more generic and it is extended to "administrative codes". Specifically it considers 3 attributes for a code:

Specify the area to be verified in a generic way:

• Use a “geoCode” object having three attributes:
  • “countryCode”: code for the country where the location must be verified. This is necessary because the values of zip codes or administrative codes make sense only for the country where they belong to.
  • “codeType”: the type of code to be used. E.g., “zip”, “adminLevel3”, etc.
  • “codeValue”: value of the code itself. E.g., “75016”, “492755”.

There is a PR on hold, #47, that was focused on PostalCodes. With this requirement it would be needed to support any kind of codeType, which may be very specific to each country, and it may be easily extensible in the future.

We could define a generic CodeArea which may support any kind of code:

    Area:
      properties: 
        areaType:
          type: string
          description: Type of this area.
      required:
        - areaType
      discriminator: 
        propertyName: areaType
        mapping: 
          Circle:  "#/components/schemas/Circle"
          Code: "#/components/schemas/CodeArea"
    CodeArea:
      description: Area associated to an administrative or geographical code
      allOf:
        - $ref: '#/components/schemas/Area'
        - type: object
          properties:
            country:
              type: string
              pattern: "^[A-Z]{2}$"
              description: ISO 3166-1 alpha-2 code for the country. Uppercase. If not specified, each implementation may assume a default value.
            codeType:
              type: string
              description: The type of the provided code
            codeValue:
              type: string
              description: The value of the code. Format will depend on `countryCode` and `codeValue` 
          required:
            - country
            - codeType
            - codeValue

Questions/doubts;

• Should we define an enum for codeValue, e.g. "Postal", "INSEE", etc, or leave this open. If open, how/where are supported values and formats documented or discovered?
• What are the requirements towards implementations for the support of certain types of codes, or codes within certain geographies? If open, how/where is this documented or discovered?
• What is the expected behaviour when certain country + codeType is not supported?

[RogerJL]

Much better, with good use case examples!

[javier-carrocalabor]

Please find attached the proposal I presented on 26th sept. You can take it as a starting point to help decide whether using postal codes and/or administrative divisions is a good solution as a standardization for these codes. AdminCode Proposal - Draft_20230926.docx

[pratishthakhattar]

@javier-carrocalabor and @jgarciahospital thanks for sharing the proposals. however, I the relevance of taking geocodes as inputs can have constraints by geography:

• pincode / admin division level precision has low accuracy in India, even if we use Google APIs
• there is incremental work needed by the client app to identify these zones and send as an input
• in most use cases for fraud, clients have requested for higher level of precision i.e. 500m - 1Km radius. Validating at geocode levels will not solve this purpose