Geocode a structured address

GET/geocode

Geocode a structured address

curl 'http://127.0.0.1:8080/geocode?address=10%20King%20Street&postcode=M5V%201A1'

const response = await fetch("http://127.0.0.1:8080/geocode?address=10%20King%20Street&postcode=M5V%201A1");
const answer = await response.json();

import requests

answer = requests.get(
    "http://127.0.0.1:8080/geocode",
    params={"address": "10 King Street", "postcode": "M5V 1A1"},
).json()

200 example

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

GET

/geocode

const url = 'http://127.0.0.1:8080/geocode?address=10%20King%20Street&locality=Toronto&region=Ontario&postcode=M5V%201A1&layer=address&country=NZ%2CAU';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://127.0.0.1:8080/geocode?address=10%20King%20Street&locality=Toronto&region=Ontario&postcode=M5V%201A1&layer=address&country=NZ%2CAU'

Geocodes an address given as separate fields, and returns the best match or no result. address is matched on its own, then checked against locality, region and postcode.

A house number missing from the data is interpolated between its neighbours (accuracy: interpolated), or answered with its street (accuracy: street).
A street matches postcode only when postcode data confirms it.
A different house is never returned: 10/1367 matches as written or as 1367, never as house 10.
geocoding.query is the form of the address that matched, which can differ from address.

Parameters

Query Parameters

address

required

string

>= 1 characters <= 256 characters

House number and street, without town or postcode.

Example

10 King Street

locality

string

<= 256 characters

City or town.

Example

Toronto

region

string

<= 256 characters

State, province or region.

Example

Ontario

postcode

string

<= 256 characters

Postal code.

Example

M5V 1A1

limit

integer

<= 50

Number of candidates to consider. 0, the default, lets the server choose. At most one result is returned.

layer

Kind of result: an address, a street, a POI, or an area such as a locality or region.

string

Allowed values: address country district interpolation locality neighbourhood place poi postcode region street

Consider only candidates of this layer. An unknown layer returns 400.

country

string

Return only results in these countries, as comma-separated ISO 3166-1 alpha-2 codes. A code that is not two letters returns 400. A code the Pack does not cover returns no results.

Example

NZ,AU

Responses

200

The best match, or no features when nothing matches.

application/json

A GeoJSON FeatureCollection answering /search, /autocomplete or /geocode.

object

features

required

Array<object>

One forward geocoding result.

object

geometry

required

GeoJSON Point. coordinates is [lon, lat].

object

coordinates

required

Array<number>

type

required

string

Allowed values: Point

properties

required

Properties of a forward geocoding result.

object

accuracy

required

How precisely the coordinates locate the result, most precise first.

rooftop: the address or POI itself.
interpolated: a house number placed between known neighbours.
street: a point on the street.
centroid: the centre of a mapped area.
approximate: a point standing for something larger, such as a town or postcode.

string

Allowed values: rooftop interpolated street centroid approximate

address

Address parts stated by the source record.

object

areas

Areas below the locality, outermost first (OSM addr:suburb, addr:quarter, addr:neighbourhood).

Array<string>

country

string

housenumber

string

locality

string

place

Named place the house number belongs to where there is no street (OSM addr:place).

string

postcode

string

region

string

street

string

unit

string

category

POI category, such as amenity:cafe. Present only on POIs.

string

context

Administrative areas containing the result.

object

country

object

required

Stable ID from the source data, as in a result’s id.

string

name

required

string

district

object

required

Stable ID from the source data, as in a result’s id.

string

name

required

string

locality

object

required

Stable ID from the source data, as in a result’s id.

string

name

required

string

neighbourhood

object

required

Stable ID from the source data, as in a result’s id.

string

name

required

string

place

Named area outside the administrative levels, usually an island.

object

required

Stable ID from the source data, as in a result’s id.

string

name

required

string

region

object

required

Stable ID from the source data, as in a result’s id.

string

name

required

string

subdistrict

object

required

Stable ID from the source data, as in a result’s id.

string

name

required

string

sublocality

object

required

Stable ID from the source data, as in a result’s id.

string

name

required

string

subregion

object

required

Stable ID from the source data, as in a result’s id.

string

name

required

string

required

Stable ID from the source data, such as osm:node:123.

string

label

required

One-line display label: name followed by its location.

string

layer

required

Kind of result: an address, a street, a POI, or an area such as a locality or region.

string

Allowed values: address country district interpolation locality neighbourhood place poi postcode region street

name

required

House number and street for an address (12 King Street West), or the name of a street, area or POI.

string

record_id

required

Row of the record in this Pack. Changes between Pack builds.

integer format: int64

source

required

Source data the result comes from.

object

dataset

required

string

derived_from

string

object_id

integer format: int64

object_type

Source object type: an OSM node, way or relation, or a row of an address dataset such as OpenAddresses.

string

Allowed values: node way relation row

record_count

integer format: int64

confidence

Probability, from 0 to 1, that this is the address the query asks for. Of results at 0.8, about 8 in 10 are correct. Present only when the Pack is calibrated. 0 on a fallback result.

number format: float

<= 1

fallback

true when no match was found and the result is the most precise area the query names instead: its postcode, a town or other area, its region or its country. layer says which. Absent otherwise.

boolean

score

required

Text relevance. Higher is better. Comparable only within one response: use confidence to judge a single result.

number format: float

type

required

string

Allowed values: Feature

geocoding

required

The query, API version and data attribution.

object

attribution

required

Attribution required by the data licence.

string

Allowed values: © OpenStreetMap contributors, ODbL

query

required

Query as received, trimmed, with each run of whitespace collapsed to one space.

string

version

required

API version. Changes only when a field is removed or changes meaning. New optional fields keep the version.

string

Allowed values: 1

type

required

string

Allowed values: FeatureCollection

Example

{
  "features": [
    {
      "geometry": {
        "type": "Point"
      },
      "properties": {
        "accuracy": "rooftop",
        "layer": "address",
        "source": {
          "object_type": "node"
        }
      },
      "type": "Feature"
    }
  ],
  "geocoding": {
    "attribution": "© OpenStreetMap contributors, ODbL",
    "version": "1"
  },
  "type": "FeatureCollection"
}

Headers

X-Request-Id

string

<= 128 characters

ID the request is logged under: the request’s own X-Request-Id when it sent one. Include it in bug reports.

400

address is empty or too long, another field is too long, limit is too large, or a parameter is malformed.

application/problem+json

Problem

Error response, an RFC 9457 problem document.

object

detail

Human-readable explanation. Absent on 500 errors.

string

error_code

required

Stable error code. Branch on this.

string

Allowed values: invalid_query invalid_coordinate limit_too_large malformed_parameter not_found method_not_allowed internal_error

invalid_params

Rejected parameters. Present only when the error is about parameters.

Array<object>

A rejected parameter.

object

name

required

Parameter name.

string

reason

required

Why it was rejected.

string

request_id

ID the request is logged under. Include it in bug reports.

string

status

required

integer format: int32

>= 400 <= 599

title

required

Name of the HTTP status. Do not branch on it.

string

type

required

URI identifying the problem type. Currently always about:blank.

string

Example

{
  "detail": "q must not be empty",
  "error_code": "invalid_query",
  "invalid_params": [
    {
      "name": "limit",
      "reason": "must be at most 50"
    }
  ],
  "request_id": "01JA7Q2K3M4N5P6Q7R8S9T0V1W",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Headers

X-Request-Id

string

<= 128 characters

ID the request is logged under: the request’s own X-Request-Id when it sent one. Include it in bug reports.

405

Method not allowed. The route accepts GET only.

application/problem+json

Problem

Error response, an RFC 9457 problem document.

object

detail

Human-readable explanation. Absent on 500 errors.

string

error_code

required

Stable error code. Branch on this.

string

Allowed values: invalid_query invalid_coordinate limit_too_large malformed_parameter not_found method_not_allowed internal_error

invalid_params

Rejected parameters. Present only when the error is about parameters.

Array<object>

A rejected parameter.

object

name

required

Parameter name.

string

reason

required

Why it was rejected.

string

request_id

ID the request is logged under. Include it in bug reports.

string

status

required

integer format: int32

>= 400 <= 599

title

required

Name of the HTTP status. Do not branch on it.

string

type

required

URI identifying the problem type. Currently always about:blank.

string

Example

{
  "detail": "q must not be empty",
  "error_code": "invalid_query",
  "invalid_params": [
    {
      "name": "limit",
      "reason": "must be at most 50"
    }
  ],
  "request_id": "01JA7Q2K3M4N5P6Q7R8S9T0V1W",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Headers

Allow

string

Example

GET

Methods the route accepts.

X-Request-Id

string

<= 128 characters

ID the request is logged under: the request’s own X-Request-Id when it sent one. Include it in bug reports.

500

Internal server error.

application/problem+json

Problem

Error response, an RFC 9457 problem document.

object

detail

Human-readable explanation. Absent on 500 errors.

string

error_code

required

Stable error code. Branch on this.

string

Allowed values: invalid_query invalid_coordinate limit_too_large malformed_parameter not_found method_not_allowed internal_error

invalid_params

Rejected parameters. Present only when the error is about parameters.

Array<object>

A rejected parameter.

object

name

required

Parameter name.

string

reason

required

Why it was rejected.

string

request_id

ID the request is logged under. Include it in bug reports.

string

status

required

integer format: int32

>= 400 <= 599

title

required

Name of the HTTP status. Do not branch on it.

string

type

required

URI identifying the problem type. Currently always about:blank.

string

Example

{
  "detail": "q must not be empty",
  "error_code": "invalid_query",
  "invalid_params": [
    {
      "name": "limit",
      "reason": "must be at most 50"
    }
  ],
  "request_id": "01JA7Q2K3M4N5P6Q7R8S9T0V1W",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Headers

X-Request-Id

string

<= 128 characters

ID the request is logged under: the request’s own X-Request-Id when it sent one. Include it in bug reports.