Nominatim forward geocoding - search locations by name
Search for locations by name, address, or place using OpenStreetMap Nominatim. The included example and response schema describe the default jsonv2 format. Other response formats and the complete parameter reference are documented by Nominatim: https://nominatim.org/release-docs/latest/api/Search/. This proxy removes the top-level licence field.
Using this data in a voice model?
The Voice Model-Ready endpoint preserves answer-critical transit facts while reducing response tokens and map-only data.
View the Voice Model-Ready endpoint →Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
q | string | Yes | Search query (free-form address or place name) | London Eye |
format | string | No | Output format | jsonv2 |
limit | integer | No | Maximum number of results to return | 5 |
addressdetails | integer | No | Include detailed address breakdown (0 or 1) | 1 |
countrycodes | string | No | Comma-separated ISO 3166-1alpha2 country codes to limit search | gb,us |
accept-language | string | No | Preferred language for results (ISO 639-1 codes) | en |
Try It Out
Required parameters only
curl -H "capi-key: Bearer YOUR_API_KEY" \
-H "capi-host: busmaps.com" \
"https://capi.busmaps.com:8443/v1/nominatim/search?q=London Eye"Common usage with optional parameters
curl -H "capi-key: Bearer YOUR_API_KEY" \
-H "capi-host: busmaps.com" \
"https://capi.busmaps.com:8443/v1/nominatim/search?q=London Eye&limit=5"Popular parameters
curl -H "capi-key: Bearer YOUR_API_KEY" \
-H "capi-host: busmaps.com" \
"https://capi.busmaps.com:8443/v1/nominatim/search?q=London Eye&format=jsonv2&limit=5&addressdetails=1&countrycodes=gb,us&accept-language=en"Response Example
[
{
"address": {
"ISO3166-2-lvl4": "GB-ENG",
"ISO3166-2-lvl8": "GB-LBH",
"city": "London",
"city_district": "London Borough of Lambeth",
"country": "United Kingdom",
"country_code": "gb",
"postcode": "SE1 7PB",
"quarter": "South Bank",
"road": "Westminster Bridge Road",
"state": "England",
"state_district": "Greater London",
"suburb": "Lambeth",
"tourism": "London Eye"
},
"addresstype": "tourism",
"boundingbox": [
"51.5027354",
"51.5039478",
"-0.1198608",
"-0.1194922"
],
"category": "tourism",
"display_name": "London Eye, Westminster Bridge Road, South Bank, Lambeth, London Borough of Lambeth, London, Greater London, England, SE1 7PB, United Kingdom",
"importance": 9.99999999995449e-6,
"lat": "51.5033416",
"lon": "-0.11967649999999999",
"name": "London Eye",
"osm_id": 204068874,
"osm_type": "way",
"place_id": 275272080,
"place_rank": 30,
"type": "attraction"
},
{
"address": {
"ISO3166-2-lvl6": "AL-10",
"amenity": "London Eye",
"city": "Shkod\u00ebr",
"country": "Shqip\u00ebria",
"country_code": "al",
"county": "Qarku i Shkodr\u00ebs",
"house_number": "6",
"municipality": "Bashkia Shkod\u00ebr",
"postcode": "4001",
"quarter": "Vasil Shanto",
"road": "Rruga Dr. Selaudin Bekteshi",
"state": "Shqip\u00ebria Veriore",
"suburb": "Lagjja 3"
},
"addresstype": "amenity",
"boundingbox": [
"42.0685708",
"42.0686708",
"19.5142695",
"19.5143695"
],
"category": "amenity",
"display_name": "London Eye, 6, Rruga Dr. Selaudin Bekteshi, Vasil Shanto, Lagjja 3, Shkod\u00ebr, Bashkia Shkod\u00ebr, Qarku i Shkodr\u00ebs, Shqip\u00ebria Veriore, 4001, Shqip\u00ebria",
"importance": 9.99999999995449e-6,
"lat": "42.0686208",
"lon": "19.5143195",
"name": "London Eye",
"osm_id": 3877861155,
"osm_type": "node",
"place_id": 55383262,
"place_rank": 30,
"type": "bar"
}
]Response Schema
View JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Nominatim Forward Geocoding Response (format=jsonv2)",
"type": "array",
"items": {
"type": "object",
"properties": {
"address": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City"
},
"amenity": {
"type": "string",
"description": "Amenity name/type at the location"
},
"state": {
"type": "string",
"description": "State/region"
},
"postcode": {
"type": "string",
"description": "Postal code"
},
"municipality": {
"type": "string",
"description": "Municipality"
},
"highway": {
"type": "string",
"description": "Highway feature at the location"
},
"country": {
"type": "string",
"description": "Country name"
},
"ISO3166-2-lvl4": {
"type": "string",
"description": "ISO 3166-2 subdivision code (level 4)"
},
"road": {
"type": "string",
"description": "Street/road name"
},
"city_district": {
"type": "string",
"description": "City district"
},
"tourism": {
"type": "string",
"description": "Tourism feature at the location"
},
"country_code": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"ISO3166-2-lvl8": {
"type": "string",
"description": "ISO 3166-2 subdivision code (level 8)"
},
"state_district": {
"type": "string",
"description": "State district"
},
"suburb": {
"type": "string",
"description": "Suburb"
},
"quarter": {
"type": "string",
"description": "Quarter"
},
"county": {
"type": "string",
"description": "County"
},
"house_number": {
"type": "string",
"description": "House number"
},
"ISO3166-2-lvl6": {
"type": "string",
"description": "ISO 3166-2 subdivision code (level 6)"
}
},
"required": [
"city",
"road",
"state",
"postcode",
"country_code",
"suburb",
"quarter",
"country"
],
"description": "Address components breakdown (if addressdetails=1)"
},
"osm_type": {
"type": "string",
"description": "OpenStreetMap element type (node, way, relation)"
},
"importance": {
"type": "number",
"description": "Search result importance score"
},
"addresstype": {
"type": "string",
"description": "Type of address component returned"
},
"name": {
"type": "string",
"description": "Name of the place"
},
"boundingbox": {
"type": "array",
"items": {
"type": "string"
},
"description": "Bounding box [minLat, maxLat, minLon, maxLon] as decimal-degree strings"
},
"type": {
"type": "string",
"description": "OSM type (attraction, museum, bus_stop, etc.)"
},
"place_id": {
"type": "integer",
"description": "Unique identifier for the place in OSM Nominatim"
},
"lon": {
"type": "string",
"description": "Longitude of the result as a decimal-degree string"
},
"osm_id": {
"type": "integer",
"description": "OpenStreetMap element ID"
},
"lat": {
"type": "string",
"description": "Latitude of the result as a decimal-degree string"
},
"place_rank": {
"type": "integer",
"description": "Nominatim importance rank of the place"
},
"category": {
"type": "string",
"description": "OSM category/class (highway, building, amenity, tourism, etc.)"
},
"display_name": {
"type": "string",
"description": "Full human-readable address"
}
},
"required": [
"type",
"osm_type",
"place_id",
"importance",
"category",
"lon",
"osm_id",
"addresstype",
"lat",
"display_name",
"place_rank",
"name",
"boundingbox"
]
}
}Response Codes
200
Search completed successfully (may return empty array if no results)400
Invalid search parameters500
Internal server error