openapi: 3.0.3
info:
  title: Nominatim API
  description: |
    Nominatim is an open-source search engine for OpenStreetMap data. It can be
    used to find places by name and address (forward geocoding) and to derive
    address information from coordinates (reverse geocoding). Nominatim is
    developed under the BSD 2-Clause license by the OpenStreetMap Search team
    (osm-search) and is hosted at https://nominatim.openstreetmap.org by the
    OpenStreetMap Foundation as a free public service.

    Self-hosted deployments are common; commercial hosted Nominatim is also
    available from MapTiler, LocationIQ, and Geocode Earth, among others.

    Use of the public OSMF instance is governed by the Nominatim Usage Policy:
    https://operations.osmfoundation.org/policies/nominatim/ — a hard limit of
    no more than 1 request per second is enforced across all your traffic, and
    a meaningful HTTP User-Agent identifying your application is required.
  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: Search
    description: Forward geocoding — search OSM objects by name or address.
  - name: Reverse
    description: Reverse geocoding — find the closest OSM object to a coordinate.
  - name: Lookup
    description: Look up address details for OSM objects by their OSM ID.
  - name: Details
    description: Internal place details, intended for debugging.
  - name: Status
    description: Service and database status reporting.
  - name: Deletable
    description: Objects removed from OpenStreetMap but retained in Nominatim.
  - name: Polygons
    description: Problematic polygon data detected by the system.
paths:
  /search:
    get:
      operationId: search
      tags: [Search]
      summary: Search OSM Objects By Name Or Address
      description: |
        Forward-geocode a free-form or structured query and return matching
        OSM objects. Use the free-form `q` parameter or one of the structured
        parameters (`amenity`, `street`, `city`, `county`, `state`, `country`,
        `postalcode`) — the two query styles cannot be combined.
      parameters:
        - $ref: '#/components/parameters/Query'
        - $ref: '#/components/parameters/Amenity'
        - $ref: '#/components/parameters/Street'
        - $ref: '#/components/parameters/City'
        - $ref: '#/components/parameters/County'
        - $ref: '#/components/parameters/State'
        - $ref: '#/components/parameters/Country'
        - $ref: '#/components/parameters/Postalcode'
        - $ref: '#/components/parameters/Format'
        - $ref: '#/components/parameters/JsonCallback'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/AddressDetails'
        - $ref: '#/components/parameters/ExtraTags'
        - $ref: '#/components/parameters/NameDetails'
        - $ref: '#/components/parameters/AcceptLanguage'
        - $ref: '#/components/parameters/CountryCodes'
        - $ref: '#/components/parameters/ExcludePlaceIds'
        - $ref: '#/components/parameters/Viewbox'
        - $ref: '#/components/parameters/Bounded'
        - $ref: '#/components/parameters/PolygonGeoJSON'
        - $ref: '#/components/parameters/PolygonKML'
        - $ref: '#/components/parameters/PolygonSVG'
        - $ref: '#/components/parameters/PolygonText'
        - $ref: '#/components/parameters/PolygonThreshold'
        - $ref: '#/components/parameters/Dedupe'
        - $ref: '#/components/parameters/Layer'
        - $ref: '#/components/parameters/FeatureType'
        - $ref: '#/components/parameters/Email'
        - $ref: '#/components/parameters/Debug'
      responses:
        '200':
          description: A list of matching places.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Place'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /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'
  /lookup:
    get:
      operationId: lookup
      tags: [Lookup]
      summary: Look Up Address Details For OSM Objects
      description: |
        Look up address details for one or more OSM objects identified by their
        OSM type and ID. Up to 50 IDs may be passed per request.
      parameters:
        - name: osm_ids
          in: query
          required: true
          description: |
            Comma-separated list of OSM IDs each prefixed with type
            (N=node, W=way, R=relation). Maximum 50 IDs per request.
          schema:
            type: string
            example: R146656,W104393803,N240109189
        - $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/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: An array of matching places.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Place'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /details:
    get:
      operationId: details
      tags: [Details]
      summary: Show Internal Place Details
      description: |
        Show internal details for an object. Intended for debugging — the
        endpoint is not part of the stable API surface and the place_id is not
        portable across Nominatim installations.
      parameters:
        - name: osmtype
          in: query
          description: OSM object type (N=node, W=way, R=relation).
          schema:
            type: string
            enum: [N, W, R]
        - name: osmid
          in: query
          description: OSM object ID.
          schema:
            type: integer
            format: int64
        - name: class
          in: query
          description: |
            Optional OSM tag key used to disambiguate between multiple places
            originating from the same OSM object.
          schema:
            type: string
        - name: place_id
          in: query
          description: |
            Internal Nominatim place identifier. Not portable across Nominatim
            instances.
          schema:
            type: integer
            format: int64
        - $ref: '#/components/parameters/JsonCallback'
        - $ref: '#/components/parameters/Format'
        - name: addressdetails
          in: query
          description: Include a breakdown of the address into elements.
          schema:
            type: integer
            enum: [0, 1]
            default: 0
        - name: keywords
          in: query
          description: Include name and address keywords used for indexing.
          schema:
            type: integer
            enum: [0, 1]
            default: 0
        - name: linkedplaces
          in: query
          description: Include details for linked places.
          schema:
            type: integer
            enum: [0, 1]
            default: 1
        - name: hierarchy
          in: query
          description: Include dependent POIs and addresses.
          schema:
            type: integer
            enum: [0, 1]
            default: 0
        - name: group_hierarchy
          in: query
          description: Group the hierarchy output by element type.
          schema:
            type: integer
            enum: [0, 1]
            default: 0
        - $ref: '#/components/parameters/PolygonGeoJSON'
        - $ref: '#/components/parameters/AcceptLanguage'
      responses:
        '200':
          description: Internal place details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaceDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
  /status:
    get:
      operationId: status
      tags: [Status]
      summary: Report Service And Database Status
      description: |
        Report on the state of the Nominatim service and its underlying
        database. Useful for health checks.
      parameters:
        - name: format
          in: query
          description: Response format.
          schema:
            type: string
            enum: [text, json]
            default: text
      responses:
        '200':
          description: Service is healthy. JSON response includes data update timestamp and versions.
          content:
            text/plain:
              schema:
                type: string
                example: OK
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '500':
          description: Service or database error (text format only).
          content:
            text/plain:
              schema:
                type: string
                example: 'ERROR: Database connection failed'
  /deletable:
    get:
      operationId: deletable
      tags: [Deletable]
      summary: List Objects Deleted From OSM But Retained In Nominatim
      description: |
        List OSM objects that have been deleted upstream in OpenStreetMap but
        are still present in the Nominatim database. Used for data quality
        monitoring.
      responses:
        '200':
          description: HTML or JSON listing of deletable objects.
          content:
            text/html:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  type: object
  /polygons:
    get:
      operationId: polygons
      tags: [Polygons]
      summary: List Problematic Polygon Geometries
      description: |
        List polygons whose geometries the Nominatim importer flagged as
        broken or otherwise problematic. Used for data quality monitoring.
      responses:
        '200':
          description: HTML or JSON listing of problematic polygons.
          content:
            text/html:
              schema:
                type: string
            application/json:
              schema:
                type: array
                items:
                  type: object
components:
  parameters:
    Query:
      name: q
      in: query
      description: Free-form query string. Cannot be combined with structured query parameters.
      schema:
        type: string
        example: 135 pilkington avenue, birmingham
    Amenity:
      name: amenity
      in: query
      description: Name or type of point of interest.
      schema:
        type: string
    Street:
      name: street
      in: query
      description: House number and street name.
      schema:
        type: string
    City:
      name: city
      in: query
      schema:
        type: string
    County:
      name: county
      in: query
      schema:
        type: string
    State:
      name: state
      in: query
      schema:
        type: string
    Country:
      name: country
      in: query
      schema:
        type: string
    Postalcode:
      name: postalcode
      in: query
      schema:
        type: string
    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
    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
    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
    Format:
      name: format
      in: query
      description: Output format.
      schema:
        type: string
        enum: [xml, json, jsonv2, geojson, geocodejson]
        default: jsonv2
    JsonCallback:
      name: json_callback
      in: query
      description: Wrap JSON output in a JSONP callback.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: Maximum number of returned results.
      schema:
        type: integer
        minimum: 1
        maximum: 40
        default: 10
    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
    NameDetails:
      name: namedetails
      in: query
      description: Include a full list of names for the result.
      schema:
        type: integer
        enum: [0, 1]
        default: 0
    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
    CountryCodes:
      name: countrycodes
      in: query
      description: Comma-separated list of ISO 3166-1 alpha-2 country codes to limit results to.
      schema:
        type: string
        example: us,ca,mx
    ExcludePlaceIds:
      name: exclude_place_ids
      in: query
      description: Comma-separated list of place IDs to exclude from the result set.
      schema:
        type: string
    Viewbox:
      name: viewbox
      in: query
      description: |
        Bounding box `x1,y1,x2,y2` (longitudes and latitudes) used to bias
        results toward a geographic area.
      schema:
        type: string
        example: '-180,-90,180,90'
    Bounded:
      name: bounded
      in: query
      description: When set, restrict results strictly to the viewbox.
      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
    PolygonKML:
      name: polygon_kml
      in: query
      description: Output geometry as KML.
      schema:
        type: integer
        enum: [0, 1]
        default: 0
    PolygonSVG:
      name: polygon_svg
      in: query
      description: Output geometry as SVG.
      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
    Dedupe:
      name: dedupe
      in: query
      description: Remove duplicate hits from the result set.
      schema:
        type: integer
        enum: [0, 1]
        default: 1
    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
    FeatureType:
      name: featureType
      in: query
      description: Restrict search results to a single feature type.
      schema:
        type: string
        enum: [country, state, city, settlement]
    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
    Debug:
      name: debug
      in: query
      description: Return verbose HTML output containing internal debugging information.
      schema:
        type: integer
        enum: [0, 1]
        default: 0
  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'
  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).
    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
    PlaceDetails:
      type: object
      description: Verbose internal details for a single place.
      properties:
        place_id:
          type: integer
          format: int64
        parent_place_id:
          type: integer
          format: int64
        osm_type:
          type: string
        osm_id:
          type: integer
          format: int64
        category:
          type: string
        type:
          type: string
        admin_level:
          type: integer
        localname:
          type: string
        names:
          type: object
          additionalProperties:
            type: string
        addresstags:
          type: object
          additionalProperties:
            type: string
        extratags:
          type: object
          additionalProperties:
            type: string
        calculated_postcode:
          type: string
        country_code:
          type: string
        indexed_date:
          type: string
          format: date-time
        importance:
          type: number
          format: double
        calculated_importance:
          type: number
          format: double
        rank_address:
          type: integer
        rank_search:
          type: integer
        isarea:
          type: boolean
        centroid:
          type: object
          properties:
            type:
              type: string
              example: Point
            coordinates:
              type: array
              items:
                type: number
                format: double
              minItems: 2
              maxItems: 2
        geometry:
          type: object
          description: GeoJSON geometry (when polygon_geojson=1).
        address:
          type: array
          items:
            type: object
        keywords:
          type: object
        hierarchy:
          type: object
        linked_places:
          type: array
          items:
            type: object
    Status:
      type: object
      description: Service and database status.
      properties:
        status:
          type: integer
          description: Numeric status code (0 means OK).
          example: 0
        message:
          type: string
          example: OK
        data_updated:
          type: string
          format: date-time
          example: '2026-05-04T14:47:00+00:00'
        software_version:
          type: string
          example: 4.5.0
        database_version:
          type: string
          example: 4.5.0
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string