Reverse geocode a point

GET/reverse

Reverse geocode a point

curl 'http://127.0.0.1:8080/reverse?lon=-79.0&lat=43.0'

const response = await fetch("http://127.0.0.1:8080/reverse?lon=-79.0&lat=43.0");
const answer = await response.json();

import requests

answer = requests.get(
    "http://127.0.0.1:8080/reverse",
    params={"lon": "-79.0", "lat": "43.0"},
).json()

200 example

{
  "features": [
    {
      "geometry": {
        "coordinates": [
          -79.0,
          43.0
        ],
        "type": "Point"
      },
      "properties": {
        "accuracy": "rooftop",
        "address": {
          "housenumber": "10",
          "postcode": "M5V 1A1",
          "street": "King Street"
        },
        "context": {
          "country": {
            "id": "osm:relation:1",
            "name": "Canada"
          },
          "locality": {
            "id": "osm:relation:3",
            "name": "Toronto"
          },
          "region": {
            "id": "osm:relation:2",
            "name": "Ontario"
          }
        },
        "distance_m": 0.0,
        "id": "osm:node:10",
        "label": "10 King Street, M5V 1A1",
        "layer": "address",
        "name": "10 King Street",
        "record_id": 3,
        "source": {
          "dataset": "osm",
          "object_id": 10,
          "object_type": "node"
        }
      },
      "type": "Feature"
    },
    {
      "geometry": {
        "coordinates": [
          -79.0,
          43.0
        ],
        "type": "Point"
      },
      "properties": {
        "accuracy": "centroid",
        "id": "osm:relation:3",
        "label": "Toronto",
        "layer": "locality",
        "name": "Toronto",
        "record_id": 2,
        "source": {
          "dataset": "osm",
          "object_id": 3,
          "object_type": "relation"
        }
      },
      "type": "Feature"
    },
    {
      "geometry": {
        "coordinates": [
          -79.0,
          43.0
        ],
        "type": "Point"
      },
      "properties": {
        "accuracy": "centroid",
        "id": "osm:relation:2",
        "label": "Ontario",
        "layer": "region",
        "name": "Ontario",
        "record_id": 1,
        "source": {
          "dataset": "osm",
          "object_id": 2,
          "object_type": "relation"
        }
      },
      "type": "Feature"
    },
    {
      "geometry": {
        "coordinates": [
          -79.0,
          43.0
        ],
        "type": "Point"
      },
      "properties": {
        "accuracy": "centroid",
        "id": "osm:relation:1",
        "label": "Canada",
        "layer": "country",
        "name": "Canada",
        "record_id": 0,
        "source": {
          "dataset": "osm",
          "object_id": 1,
          "object_type": "relation"
        }
      },
      "type": "Feature"
    }
  ],
  "geocoding": {
    "attribution": "© OpenStreetMap contributors, ODbL",
    "point": {
      "lat": 43.0,
      "lon": -79.0
    },
    "version": "1"
  },
  "type": "FeatureCollection"
}

GET

/reverse

const url = 'http://127.0.0.1:8080/reverse?lon=-79.3832&lat=43.6532';
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/reverse?lon=-79.3832&lat=43.6532'

Returns the nearest address or street to a point, followed by the areas that contain the point, most precise first. Only the first result carries distance_m.

Parameters

Query Parameters

lon

required

number format: double

>= -180 <= 180

Longitude in degrees.

Example

-79.3832

lat

required

number format: double

>= -90 <= 90

Latitude in degrees.

Example

43.6532

Responses

200

Results at the point, most precise first. features is empty when nothing is near.

application/json

A GeoJSON FeatureCollection answering /reverse.

object

features

required

Array<object>

One reverse geocoding result: the address or street at the point, or an area containing it.

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 reverse 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

distance_m

Distance from the queried point in meters. Present only on the address or street result, not on areas.

number format: double

type

required

string

Allowed values: Feature

geocoding

required

The queried point, API version and data attribution.

object

attribution

required

Attribution required by the data licence.

string

Allowed values: © OpenStreetMap contributors, ODbL

point

required

Queried point.

object

lat

required

number format: double

lon

required

number format: double

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

lon or lat is missing or out of range.

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.