Nominatim Reverse API

openapi: 3.2.0
info:
  title: Nominatim Reverse API
  description: Nominatim is an open-source search engine for OpenStreetMap data.
  version: 4.5.0
  license:
    name: BSD-2-Clause
    url: https://github.com/osm-search/Nominatim/blob/master/COPYING
  contact:
    name: OpenStreetMap Search Team
    url: https://nominatim.org/
  termsOfService: https://operations.osmfoundation.org/policies/nominatim/
servers:
- url: https://nominatim.openstreetmap.org
  description: Public Nominatim instance operated by the OpenStreetMap Foundation
- url: https://{host}
  description: Self-hosted Nominatim instance
  variables:
    host:
      default: nominatim.example.org
      description: Hostname of a self-hosted Nominatim deployment
tags:
- name: Reverse
  description: Reverse geocoding — find the closest OSM object to a coordinate.
paths:
  /reverse:
    get:
      operationId: reverse
      tags:
      - Reverse
      summary: Reverse Geocode A Coordinate
      description: 'Find the closest OSM object to a latitude/longitude pair and return its

        address information. The result is the closest suitable feature for the

        requested zoom level rather than a literal address for the exact point.'
      parameters:
      - $ref: '#/components/parameters/Lat'
      - $ref: '#/components/parameters/Lon'
      - $ref: '#/components/parameters/Zoom'
      - $ref: '#/components/parameters/Format'
      - $ref: '#/components/parameters/JsonCallback'
      - $ref: '#/components/parameters/AddressDetails'
      - $ref: '#/components/parameters/ExtraTags'
      - $ref: '#/components/parameters/NameDetails'
      - $ref: '#/components/parameters/AcceptLanguage'
      - $ref: '#/components/parameters/Layer'
      - $ref: '#/components/parameters/PolygonGeoJSON'
      - $ref: '#/components/parameters/PolygonKML'
      - $ref: '#/components/parameters/PolygonSVG'
      - $ref: '#/components/parameters/PolygonText'
      - $ref: '#/components/parameters/PolygonThreshold'
      - $ref: '#/components/parameters/Email'
      - $ref: '#/components/parameters/Debug'
      responses:
        '200':
          description: A single matching place.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Place'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    AcceptLanguage:
      name: accept-language
      in: query
      description: 'Preferred language order for showing search results, in browser-style

        format (e.g. `en-US,en;q=0.5`). Overrides the HTTP Accept-Language

        header.

        '
      schema:
        type: string
    Debug:
      name: debug
      in: query
      description: Return verbose HTML output containing internal debugging information.
      schema:
        type: integer
        enum:
        - 0
        - 1
        default: 0
    AddressDetails:
      name: addressdetails
      in: query
      description: Include a breakdown of the address into elements.
      schema:
        type: integer
        enum:
        - 0
        - 1
        default: 0
    ExtraTags:
      name: extratags
      in: query
      description: Include additional information (Wikipedia link, opening hours, etc.).
      schema:
        type: integer
        enum:
        - 0
        - 1
        default: 0
    Format:
      name: format
      in: query
      description: Output format.
      schema:
        type: string
        enum:
        - xml
        - json
        - jsonv2
        - geojson
        - geocodejson
        default: jsonv2
    Lon:
      name: lon
      in: query
      required: true
      description: Longitude of the coordinate to reverse geocode (WGS84).
      schema:
        type: number
        format: double
        minimum: -180
        maximum: 180
        example: -1.81602098644987
    PolygonKML:
      name: polygon_kml
      in: query
      description: Output geometry as KML.
      schema:
        type: integer
        enum:
        - 0
        - 1
        default: 0
    PolygonGeoJSON:
      name: polygon_geojson
      in: query
      description: Output geometry as GeoJSON.
      schema:
        type: integer
        enum:
        - 0
        - 1
        default: 0
    PolygonText:
      name: polygon_text
      in: query
      description: Output geometry as WKT.
      schema:
        type: integer
        enum:
        - 0
        - 1
        default: 0
    PolygonThreshold:
      name: polygon_threshold
      in: query
      description: Simplification tolerance for polygon output, in degrees.
      schema:
        type: number
        format: double
        minimum: 0
        default: 0
    PolygonSVG:
      name: polygon_svg
      in: query
      description: Output geometry as SVG.
      schema:
        type: integer
        enum:
        - 0
        - 1
        default: 0
    Lat:
      name: lat
      in: query
      required: true
      description: Latitude of the coordinate to reverse geocode (WGS84).
      schema:
        type: number
        format: double
        minimum: -90
        maximum: 90
        example: 52.5487429714954
    JsonCallback:
      name: json_callback
      in: query
      description: Wrap JSON output in a JSONP callback.
      schema:
        type: string
    NameDetails:
      name: namedetails
      in: query
      description: Include a full list of names for the result.
      schema:
        type: integer
        enum:
        - 0
        - 1
        default: 0
    Zoom:
      name: zoom
      in: query
      description: 'Level of administrative detail required. 3=country, 5=state, 8=county,

        10=city, 12=town/borough, 13=village/suburb, 14=neighbourhood, 15=any

        settlement, 16=major streets, 17=major and minor streets, 18=building.

        '
      schema:
        type: integer
        minimum: 0
        maximum: 18
        default: 18
    Layer:
      name: layer
      in: query
      description: 'Restrict results to one or more feature layers. Comma-separated list of

        `address`, `poi`, `railway`, `natural`, `manmade`.

        '
      schema:
        type: string
        example: address,poi
    Email:
      name: email
      in: query
      description: 'Email address identifying you when making high-volume requests. Required

        by the OSMF usage policy at sustained traffic levels.

        '
      schema:
        type: string
        format: email
  schemas:
    Place:
      type: object
      description: A single Nominatim place result.
      properties:
        place_id:
          type: integer
          format: int64
          description: Internal Nominatim place ID. Not portable across installations.
        licence:
          type: string
          description: Licence and attribution text for the returned data.
          example: Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright
        osm_type:
          type: string
          enum:
          - node
          - way
          - relation
        osm_id:
          type: integer
          format: int64
        boundingbox:
          type: array
          description: '[min_lat, max_lat, min_lon, max_lon] as strings.'
          items:
            type: string
          minItems: 4
          maxItems: 4
        lat:
          type: string
          description: Latitude of the centroid.
        lon:
          type: string
          description: Longitude of the centroid.
        display_name:
          type: string
          description: Full, comma-separated address.
        class:
          type: string
          description: Main OSM tag key for this object (jsonv2 renames this to `category`).
        category:
          type: string
          description: Main OSM tag key for this object (jsonv2 only).
        type:
          type: string
          description: Main OSM tag value for this object.
        place_rank:
          type: integer
          description: Search rank of the object (jsonv2 only).
        importance:
          type: number
          format: double
          description: Computed importance rank for ordering results.
        addresstype:
          type: string
        name:
          type: string
        icon:
          type: string
          description: URL of an icon representing the result class.
        address:
          $ref: '#/components/schemas/Address'
        extratags:
          type: object
          additionalProperties:
            type: string
        namedetails:
          type: object
          additionalProperties:
            type: string
        geojson:
          type: object
          description: GeoJSON geometry of the result (when polygon_geojson=1).
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
    Address:
      type: object
      description: Structured address breakdown for a place.
      properties:
        house_number:
          type: string
        road:
          type: string
        neighbourhood:
          type: string
        suburb:
          type: string
        city:
          type: string
        town:
          type: string
        village:
          type: string
        municipality:
          type: string
        county:
          type: string
        state_district:
          type: string
        state:
          type: string
        postcode:
          type: string
        country:
          type: string
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code, lowercase.
      additionalProperties:
        type: string
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: 'Rate limit exceeded. The public Nominatim instance enforces a hard

        ceiling of 1 request per second across all your traffic. See

        https://operations.osmfoundation.org/policies/nominatim/.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'