Provide a list of GeoHashes in the API request

[bigludo7]

Problem description
The developer has to know & understand geohash as she/he get a list of them in the response.
We have feedback from potential users of this API to allow geohash list in the API request.
Indeed it will allow for the developer 1/to be precise on the request and 2/to know exactly the volume of the response.

This capability must no replace current area definition but an additional one. Developer must use one or the other for a call.

Possible evolution
Provide an new value of areaType that could be GEOHASHLIST and here the developer could provide a collection of geoashes 7 in the request.

Alternative solution

Additional context

[VGF-TEF]

So, with this proposal, the API can be queried in two different ways (and the response format will be the same for both types of requests):

1. Using a polygon (as it works now).
2. Using a list of geohashes.

This means that you can ask the API for a list of geohashes in different locations, geohashes that are not adjacent, and even in areas where an MNO is not providing information. We need to understand how to handle these cases.

• In the case of a partial response, the cells without data will be returned with the cell type set to NO_DATA.
• If the requested area is entirely outside the supported MNO coverage, the status field will return AREA_NOT_SUPPORTED.

Is this the way your proposal work?

[bigludo7]

Hi @VGF-TEF
Yes 2 ways to request (one or the other in - not both defined in one request) and response format same as today.

I should confess that I did not think the case where the geohashes that are not adjacent. I'm not sure this is an issue.

For the status, I'm aligned with your proposal (and it did not change current rule). Just one clarification:

• If the requested area, or the complete list of provided geohashes, is entirely outside the supported MNO coverage, the status field will return AREA_NOT_SUPPORTED

[VGF-TEF]

Hi @bigludo7:

Reviewing the proposal, we see the following implications.

Agreed
• In the case of a partial response, the cells without data will be returned with the cell type set to NO_DATA.
• If the requested area or list of geohashes is entirely outside the supported MNO coverage: response 200 OK with the status field set to AREA_NOT_SUPPORTED.

To discuss
We have to consider that giving the developer the freedom to select the geohashes could lead to situations where providing a response may be complex:

1. Non-adjacent geohashes:

• Option 1: return an error.
• Option 2: return all the geohashes.
• Option 3: only return adjacent geohashes.

2. Different-precision list of geohashes:

• Option 1: only support geohashes of the same precision (which one?).
• Option 2: support different precision geohashes if all requested precisions are supported by the MNO. If any precision is not supported, return an error.

3. Same-precision list of geohashes:

• Precision supported by the MNO: 200 OK.
• Precision not supported by the MNO: Return an error.

Proposal:
Define the areaType field as optional so each MNO can decide which areaTypes to support. If the areaType is not supported by the MNO, return an error.

[bigludo7]

Hello @VGF-TEF

Thanks for your comment.

• Regarding non-adjacent I'm not sure about the issue to manage these. I tend to think that making this adjacent check will be more costly than doing nothing and send back the info. What is your concern for non adjacent?
• precision - I tend to prefer to keep simple and only support one precision. To be consistent with the current API we should request server to manage at least precision 7 (mandatory). It's then up to document if other precision are managed.

Regarding your proposal, for me, we should keep areaType mandatory and use it as discriminator to define area definition. All operators have to manage at least POLYGON value (and optionally GEOHASH-LIST). My point is to keep same mechanism than the one used in Location retrieval/verification API for example

[VGF-TEF]

Hi @bigludo7

We addressed this topic during the last meeting, but point 8 still needs to be clarified. Please confirm that there is agreement on points 1–7.

1. A new type of AreaType named GEOHASHLIST will be created.
2. AreaType remains mandatory.
3. The GEOHASHLIST AreaType will be optional.
4. All MNOs must support at least the POLYGON AreaType, and optionally the GEOHASHLIST AreaType.
5. In the case of a partial response, cells without data will be returned with the cell type set to NO_DATA.
6. If the requested GEOHASHLIST is entirely outside the supported MNO coverage, the status field will return AREA_NOT_SUPPORTED.
7. For non-adjacent geohashes in the GEOHASHLIST, the API will return all the geohashes requested.

And:
8. For a GEOHASHLIST request containing mixed precision levels, the API will return data for the geohashes with precisions supported by the MNO, and at least precision 7, which is mandatory. --> to be confirmed. We can “force” the user to request just one precision, but we need to define how.

[bigludo7]

Hi @VGF-TEF
Agree for 1 to 7.

I also agree on your proposal to

• enforce precision 7
• for all other precision it's up to the MNO to indicate if supported
• In the case of multi-precision geohash we can add a 422 error - wdyt?

let me know if you want me to propose a PR - seems we're almost aligned.

[VGF-TEF]

Hi @bigludo7 :

Reviewing the whole API specification, it is true that there is no option to mix precisions. Even though the precision parameter is optional, it has a default value of 7, meaning that only one precision level is supported at a time. So, if a request includes a geohash list with mixed precisions, the API then, will return a 422 error.

We are going to proceed to open the PR. We will keep you posted.

Thanks.