Responses

Every answer from og is one GeoJSON FeatureCollection. Forward and reverse answers have the same shape. The only differences: forward features carry a score (and a confidence once the Pack is calibrated), and reverse features carry a distance_m.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "type": "Point", "coordinates": [-79.0, 43.0] },
      "properties": {
        "id": "osm:node:10",
        "layer": "address",
        "accuracy": "rooftop",
        "name": "10 King Street",
        "label": "10 King Street, M5V 1A1",
        "address": { "housenumber": "10", "street": "King Street", "postcode": "M5V 1A1" },
        "context": {
          "locality": { "id": "osm:relation:3", "name": "Toronto" },
          "region": { "id": "osm:relation:2", "name": "Ontario" },
          "country": { "id": "osm:relation:1", "name": "Canada" }
        },
        "score": 5.459071,
        "confidence": 0.9890131,
        "source": { "dataset": "osm", "object_type": "node", "object_id": 10 }
      }
    }
  ],
  "geocoding": {
    "version": "1",
    "query": "10 king street, m5v 1a1",
    "attribution": "© OpenStreetMap contributors, ODbL"
  }
}

Coordinates are [longitude, latitude], as GeoJSON requires.

Layers

layer says what kind of record a feature is: address, street, interpolation, postcode, poi, place, neighbourhood, locality, district, region or country. Pass layer= to a forward endpoint to only get one kind.

Accuracy

accuracy says how the point relates to the thing it names, from most to least precise:

accuracy	The point is
rooftop	the point of an address or POI
interpolated	a house number placed along a range or between its neighbours
street	a point on a street or address-range line
centroid	the centre of a mapped way or relation
approximate	a point standing for something larger, such as a town or a postcode

Score and confidence

• score ranks results within one response, highest first. It is not a probability, and it can’t be compared across queries or Packs. To judge a single result, use confidence, or accuracy and layer.
• confidence is the probability, from 0 to 1, that the result is the address the query asks for. Of results at 0.8, about 8 in 10 are correct. It is only present on a Pack calibrated with open-geocode geocode calibrate, which fits it to held-out address points.
• fallback is true when nothing matched and the result is the most precise area the query names instead, such as its postcode or town. Its confidence is 0.

Errors

Errors are RFC 9457 problem documents, served as application/problem+json. Branch on error_code, which is one of a fixed set. title and detail are prose and may be reworded.

error_code	Meaning
invalid_query	The query text can’t be searched.
invalid_coordinate	A longitude or latitude is out of range.
limit_too_large	limit is above the maximum.
malformed_parameter	A parameter couldn’t be parsed.
not_found	No such endpoint.
method_not_allowed	The API is GET-only.
internal_error	Something failed on the server.

The full schemas are in the API reference and in /openapi.json.