OpenStreetMap Geocoding API
Forward geocoding, reverse geocoding, and OSM object lookup
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/openstreetmap-geocoding-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
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)
SearchResults:
type: array
items:
$ref: '#/components/schemas/SearchResult'
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
ReverseResult:
allOf:
- $ref: '#/components/schemas/SearchResult'
- type: object
properties:
error:
type: string
description: Error message if no result found
externalDocs:
description: Nominatim API Documentation
url: https://nominatim.org/release-docs/latest/api/Overview/