openapi: 3.2.0
info:
  title: OpenStreetMap Nominatim Geocoding API
  description: 'Nominatim is the OpenStreetMap geocoding API providing search (forward geocoding), reverse geocoding, and address lookup for OSM objects. Rate limit: 1 request/second for the public instance. Requires valid User-Agent header. Open source under GNU GPL v3.'
  version: 4.4.0
  contact:
    name: Nominatim Project
    url: https://nominatim.org/
  license:
    name: ODbL 1.0
    url: https://www.openstreetmap.org/copyright
servers:
- url: https://nominatim.openstreetmap.org
  description: Nominatim public instance (1 req/sec limit)
security: []
tags:
- name: Geocoding
  description: Forward geocoding, reverse geocoding, and OSM object lookup
paths:
  /search:
    get:
      operationId: geocodeSearch
      summary: Forward geocode (search by address/name)
      description: 'Search for locations by address, place name, or structured address components. Returns geographic coordinates and address details. Rate limit: 1 request/second; User-Agent header required.'
      tags:
      - Geocoding
      parameters:
      - name: q
        in: query
        schema:
          type: string
        description: Free-form query string (incompatible with structured parameters)
      - name: street
        in: query
        schema:
          type: string
        description: 'Structured search: house number and street name'
      - name: city
        in: query
        schema:
          type: string
      - name: county
        in: query
        schema:
          type: string
      - name: state
        in: query
        schema:
          type: string
      - name: country
        in: query
        schema:
          type: string
        description: Country name or ISO 3166-1 alpha-2 code
      - name: postalcode
        in: query
        schema:
          type: string
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - jsonv2
          - geojson
          - geocodejson
          - xml
          default: jsonv2
      - name: addressdetails
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
        description: Include address breakdown in results
      - name: extratags
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
        description: Include extra OSM tags
      - name: namedetails
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
        description: Include all localized names
      - name: countrycodes
        in: query
        schema:
          type: string
        description: Comma-separated list of ISO 3166-1 alpha-2 codes to limit results
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
          maximum: 50
      - name: dedupe
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 1
      - name: bounded
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
        description: Restrict results to viewbox when combined with viewbox parameter
      - name: viewbox
        in: query
        schema:
          type: string
        description: Preferred search area as min_lon,min_lat,max_lon,max_lat
      - name: exclude_place_ids
        in: query
        schema:
          type: string
        description: Comma-separated OSM place IDs to exclude
      - name: accept-language
        in: query
        schema:
          type: string
        description: Preferred response language (BCP 47 code or comma-separated list)
      responses:
        '200':
          description: Geocoding results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
        '429':
          description: Rate limit exceeded — maximum 1 request/second
  /reverse:
    get:
      operationId: geocodeReverse
      summary: Reverse geocode (coordinates to address)
      description: Convert geographic coordinates (lat/lon) into a human-readable address. Returns the OSM object closest to the given coordinates at the specified zoom level.
      tags:
      - Geocoding
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          format: double
          minimum: -90
          maximum: 90
        description: Latitude in decimal degrees (WGS84)
      - name: lon
        in: query
        required: true
        schema:
          type: number
          format: double
          minimum: -180
          maximum: 180
        description: Longitude in decimal degrees (WGS84)
      - name: zoom
        in: query
        schema:
          type: integer
          minimum: 0
          maximum: 18
          default: 18
        description: 'Level of detail: 0=country, 3=region, 10=city, 14=suburb, 16=street, 18=building'
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - jsonv2
          - geojson
          - geocodejson
          - xml
          default: jsonv2
      - name: addressdetails
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 1
      - name: extratags
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
      - name: namedetails
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
      - name: accept-language
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Reverse geocoding result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReverseResult'
        '404':
          description: No result found for the given coordinates
  /lookup:
    get:
      operationId: lookupOSMObjects
      summary: Look up OSM objects by ID
      description: Look up address details for specific OSM objects by their type and ID. Maximum 50 IDs per request.
      tags:
      - Geocoding
      parameters:
      - name: osm_ids
        in: query
        required: true
        schema:
          type: string
        description: 'Comma-separated list of OSM IDs with type prefix: N=node, W=way, R=relation (e.g., R146656,W104393803,N240109189)'
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - jsonv2
          - geojson
          - geocodejson
          - xml
          default: jsonv2
      - name: addressdetails
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 1
      - name: extratags
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
      - name: namedetails
        in: query
        schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
      responses:
        '200':
          description: Object address details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
components:
  schemas:
    Address:
      type: object
      description: Structured address components
      properties:
        house_number:
          type: string
        road:
          type: string
        suburb:
          type: string
        neighbourhood:
          type: string
        quarter:
          type: string
        borough:
          type: string
        city:
          type: string
        town:
          type: string
        village:
          type: string
        county:
          type: string
        state:
          type: string
        state_district:
          type: string
        postcode:
          type: string
        country:
          type: string
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code (lowercase)
    ReverseResult:
      allOf:
      - $ref: '#/components/schemas/SearchResult'
      - type: object
        properties:
          error:
            type: string
            description: Error message if no result found
    SearchResult:
      type: object
      description: A single geocoding result
      properties:
        place_id:
          type: integer
          description: Internal Nominatim place identifier
        licence:
          type: string
          description: Data licence text
        osm_type:
          type: string
          enum:
          - node
          - way
          - relation
        osm_id:
          type: integer
          format: int64
        lat:
          type: string
          description: Latitude as string
        lon:
          type: string
          description: Longitude as string
        display_name:
          type: string
          description: Full formatted address string
        class:
          type: string
          description: OSM class (e.g., place, highway, amenity)
        type:
          type: string
          description: OSM type within the class (e.g., city, residential, restaurant)
        importance:
          type: number
          description: Relevance score (0-1)
        icon:
          type: string
          format: uri
        address:
          $ref: '#/components/schemas/Address'
        boundingbox:
          type: array
          items:
            type: string
          minItems: 4
          maxItems: 4
          description: Bounding box [min_lat, max_lat, min_lon, max_lon]
        extratags:
          type: object
          additionalProperties:
            type: string
        namedetails:
          type: object
          additionalProperties:
            type: string
    SearchResults:
      type: array
      items:
        $ref: '#/components/schemas/SearchResult'
externalDocs:
  description: Nominatim API Documentation
  url: https://nominatim.org/release-docs/latest/api/Overview/