Search addresses

Search addresses

curl 'http://127.0.0.1:8080/search?q=10%20King%20Street'

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.975873,
        "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": 3.1327698,
        "source": {
          "dataset": "osm",
          "object_id": 10,
          "object_type": "node"
        }
      },
      "type": "Feature"
    }
  ],
  "geocoding": {
    "attribution": "© OpenStreetMap contributors, ODbL",
    "query": "10 King Street",
    "version": "1"
  },
  "type": "FeatureCollection"
}

GET

/search

curl --request GET \
  --url 'http://127.0.0.1:8080/search?q=10%20King%20Street%2C%20Toronto&layer=address&country=NZ%2CAU&focus=-79.38%2C43.65&bbox=-79.64%2C43.58%2C-79.12%2C43.86'

• Local server on the default address.

Geocodes free-form text, such as a full address, to coordinates. Results are sorted by score, highest first.

Parameters

Query Parameters

q

required

string

>= 1 characters <= 256 characters

Text to geocode, such as a full address.

Example

10 King Street, Toronto

limit

integer

<= 50

Maximum number of results. 0, the default, lets the server choose.

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

Return only results 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

focus

string

Point to prefer results near, as lon,lat. Breaks ties between equally good matches only.

Example

-79.38,43.65

bbox

string

Return only results inside this box, as min_lon,min_lat,max_lon,max_lat. The box cannot cross the antimeridian.

Example

-79.64,43.58,-79.12,43.86

Responses

200

Matching results, highest score first.

Media typeapplication/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

id

required

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

string

name

required

string

district

object

id

required

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

string

name

required

string

locality

object

id

required

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

string

name

required

string

neighbourhood

object

id

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

id

required

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

string

name

required

string

region

object

id

required

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

string

name

required

string

subdistrict

object

id

required

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

string

name

required

string

sublocality

object

id

required

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

string

name

required

string

subregion

object

id

required

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

string

name

required

string

id

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

q is empty or too long, limit is too large, focus or bbox is out of range, or a parameter is malformed.

Media typeapplication/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.

Media typeapplication/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.

Media typeapplication/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.