Search Nominatim for voice agents
For voice models and voice agents, this endpoint reduces response tokens and keeps spoken-answer tool calls focused. Search Nominatim with the same query parameters and result order as /v1/nominatim/search, then return every matching place in a compact positional format. resultFields defines the columns in each results row. The response keeps the short name, full human-readable label, place type, coordinates and the country code when supplied by Nominatim, which is enough to disambiguate a place and continue with routing requests. Provider-specific OSM identifiers, bounds, ranking metadata and raw address maps are omitted.
Voice-ready response: This JSON REST method uses a smaller positional representation so voice models spend fewer tokens on repeated fields and map-only data. It does not accept or process audio.
The standard endpoint returns the complete application and map-oriented response for the same capability.
View the standard endpoint →Response fields and units
| Field | Format / unit | Meaning |
|---|---|---|
resultFields | [name, label, type, countryCode, lat, lon] | Column order for every results row |
results[] | Positional array | One place candidate; indexes are zero-based and match resultFields |
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
q | string | Yes | Search query (free-form address or place name) | London Eye |
format | string | No | Nominatim JSON format; the compact response is always normalized JSON | jsonv2 |
limit | integer | No | Maximum number of results to return | 5 |
addressdetails | integer | No | Include detailed address data (0 or 1); the compact response retains its country code and human-readable label | 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/compact/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/compact/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/compact/v1/nominatim/search?q=London Eye&format=jsonv2&limit=5&addressdetails=1&countrycodes=gb,us&accept-language=en"Response Example
{
"resultFields": [
"name",
"label",
"type",
"countryCode",
"lat",
"lon"
],
"results": [
[
"London Eye",
"London Eye, Westminster Bridge Road, South Bank, Lambeth, London Borough of Lambeth, London, Greater London, England, SE1 7PB, United Kingdom",
"tourism",
"GB",
51.5033416,
-0.11967649999999999
],
[
"London Eye",
"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",
"amenity",
"AL",
42.0686208,
19.5143195
],
[
"London Eye",
"London Eye, York Road, South Bank, Waterloo, London Borough of Lambeth, London, Greater London, England, SE1 7ND, United Kingdom",
"highway",
"GB",
51.5032255,
-0.1158352
]
]
}Response Schema
View JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Compact Nominatim Forward Geocoding Response",
"type": "object",
"properties": {
"resultFields": {
"type": "array",
"items": [
{
"const": "name"
},
{
"const": "label"
},
{
"const": "type"
},
{
"const": "countryCode"
},
{
"const": "lat"
},
{
"const": "lon"
}
],
"additionalItems": false,
"minItems": 6,
"maxItems": 6,
"description": "Column order for results rows"
},
"results": {
"type": "array",
"items": {
"type": "array",
"items": [
{
"type": [
"string",
"null"
],
"description": "Short place name"
},
{
"type": [
"string",
"null"
],
"description": "Full human-readable place label"
},
{
"type": [
"string",
"null"
],
"description": "Place type such as city, street, or house"
},
{
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2 country code"
},
{
"type": [
"number",
"null"
],
"description": "Latitude in decimal degrees"
},
{
"type": [
"number",
"null"
],
"description": "Longitude in decimal degrees"
}
],
"additionalItems": false,
"minItems": 6,
"maxItems": 6
},
"description": "All compact geocoding candidates returned by Nominatim"
}
},
"required": [
"resultFields",
"results"
]
}Response Codes
200
Search completed successfully (results may be empty)400
Invalid search parameters500
Internal server error