fleshing out result.ts

[missinglink]

@mxlje would it be helpful for me to better define the JSON response format schema(s)?

Geocoding results

I found someone else has already defined the envelope format for GeoJSON: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/geojson/index.d.ts

Within that we can then define our application-specific fields:

• top level geocoding property with a bunch of sub-properties such as geocoding.warnings
• the features[].properties.* properties which are all application-specific

Errors

The errors JSON format is actually different, it looks like this:

{
  "meta": {
    "version": 1,
    "status_code": 403
  },
  "results": {
    "error": {
      "type": "KeyError",
      "message": "Invalid api_key specified."
    }
  }
}

Is this something we want to tackle now or is it fine to leave it fairly generic?

[mxlje]

Response: This is exactly what we needed, great!

errors: I adjusted the error we return a bit to make the format simpler, but we could also return it as is from the API and add the rate limiting Info.

I think having a simpler error format might make sense for this library though. We don’t need to return a results section etc, we can extract the error info and return it in a bit of a more compact Form.

[mxlje]

After my initial excitement I looked a the types more closely trying to implement them, but unfortunately the main section of a feature, its properties, are not typed at all and are just a map of string: any, which we can just as well leave out in that case. You already mentioned that in your comment, I’m sorry.

I’ll see that I use the other types as a base to define our result type. https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/geojson/index.d.ts#L145

[mxlje]

This is what I have so far for an individual Feature.

Are there other values for accuracy possible? I tried a bunch of different API requests and could only get the two.

I’m not sure about addendum, I think we could leave that as any for now as I think there can be a lot of different properties coming from openstreetmap.

type Layers = 'address' |
  'borough' |
  'coarse' |
  'country' |
  'county' |
  'localadmin' |
  'locality' |
  'macrocounty' |
  'macroregion' |
  'neighbourhood' |
  'postalcode' |
  'region' |
  'street' |
  'venue'

type Sources = 'openstreetmap' | 'openaddresses' | 'geonames' | 'whosonfirst'

type Feature = {
  type: 'Feature'
  geometry: {
    type: 'Point'
    coordinates: [number, number]
  }
  properties: {
    id: string
    gid: string
    layer: Layers
    source: Sources
    source_id: string

    label: string
    name: string

    accuracy: 'centroid' | 'point'

    neighbourhood?: string
    neighbourhood_gid?: string

    borough?: string
    borough_gid?: string

    county?: string
    county_a?: string
    county_gid?: string

    locality_gid?: string
    locality?: string

    localadmin?: string
    localadmin_gid?: string

    region?: string
    region_a?: string
    region_gid?: string
    macroregion?: string
    macroregion_gid?: string

    country?: string
    country_a?: string
    country_gid?: string

    continent?: string
    continent_gid?: string

    street?: string
    housenumber?: string
    postalcode?: string

    addendum?: any
  }
  bbox?: [number, number, number, number] | [number, number, number, number, number, number]
}

[missinglink]

Hmmm this is actually quite tricky, @orangejulius there's a lot of things to consider:

sources & layers

• the "coarse" layer is an alias for all 'administrative areas'
• there are 4 valid source aliases 'osm', 'oa', 'gn', 'wof' which are just abbreviated forms of the sources above.
• we actually have an undocumented source 'uscensus'
• some locations are interpolated from other nearby results, in this case the source will be 'mixed'
• there will shortly be a new layer called intersection added, the work for this is already complete but it's not live
• there are some changes coming to how sources/layers are handled https://github.com/pelias/api/pull/1525
• there's a fair bit of server-side logic to handle these properties and how they work when combined, would it better to let the server handle validation rather than duplicate this in the client?

geometry

• one day we might want to support non-Point geometries such as LineString and Polygon, this is not required for launch but it's worth considering what will happen if/when that happens.
• is it easy enough to support all the types defined in the GeoJSON spec?
• we can also copy the bbox stuff from the spec, I'm not familiar with the 6 element version, that must be for 3D.

addendum

• yeah good call, it's a freeform field so we'll never be able to list all the properties and it'll likely change often.

accuracy

• just point and centroid from looking at the code
• there is also a field called "confidence" which is missing from above
• oh and "match_type" which isn't listed

the list of 'admin' fields

• Each 'parent' place (ie city, country, etc) has 3x fields. Eg. for 'county' we have 'county' (the name), 'county_a' (the abbreviation), 'county_gid' (the ID which combines the source and the source_id).
• The list of all possible parents: ["continent", "ocean", "empire", "country", "dependency", "marinearea", "macroregion", "region", "macrocounty", "county", "locality", "borough", "localadmin", "neighbourhood", "postalcode"]

other

• over time id and source_id have come to mean the same thing, they will always have the same value 🤷
• an array of categories are returned if requested (this is not documented)
• I need to check if we return 'unit number' as part of the address when we have it, there's partial support for unit numbers and I forget where we're at there
• I need to check how 'cross streets' are returned for results from the intersection layer, do we return both street names?

[orangejulius]

The response format documentation should be helpful here. There's definitely a lot of nuance in the details and some of the lesser-known fields like accuracy and match_type.

[mxlje]

This is all super helpful, I’ll open a PR with an updated format soon so we can review it directly in there.