Photon forward geocoding - search locations by name
Forward geocoding with prefix/autocomplete support using Photon (Komoot). Supports partial queries, location bias, bounding box filter and OSM layer/tag filters. Returns GeoJSON FeatureCollection; properties vary by result type (city/street/house/etc). The endpoint is a pass-through to the upstream Photon instance, so any Photon parameter is forwarded as-is (repeated params like layer=street&layer=house are preserved); only the parameters most relevant to typical use are documented here. Complete upstream documentation: https://github.com/komoot/photon#api.
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 →Response fields and units
| Field | Format / unit | Meaning |
|---|---|---|
features[].geometry.coordinates | [longitude, latitude] in decimal degrees | GeoJSON point coordinates |
features[].properties.extent | [minLon, maxLat, maxLon, minLat] in decimal degrees | Feature bounds when present |
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
q | string | Yes | Search query, supports partial/prefix input for autocomplete | London |
lat | number | No | Latitude for location bias (soft boost, not a hard filter) | 51.5074 |
lon | number | No | Longitude for location bias (soft boost, not a hard filter) | -0.1278 |
limit | integer | No | Maximum number of results to return | 5 |
lang | string | No | Response language supported by the current Photon upstream; omit for its default language | en |
zoom | integer | No | Map zoom level hint for search radius | 16 |
location_bias_scale | number | No | Strength of location bias from 0.0 to 1.0 | 0.2 |
bbox | string | No | Bounding box hard filter in 'minLon,minLat,maxLon,maxLat' format | -0.51,51.28,0.33,51.69 |
layer | string | No | Filter by feature layer. Can be repeated to combine multiple layers (e.g., layer=street&layer=house) | city |
osm_tag | string | No | OSM tag filter. Use 'key:value' to include or '!key' to exclude | tourism:hotel |
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/photon/api?q=London"Common usage with optional parameters
curl -H "capi-key: Bearer YOUR_API_KEY" \
-H "capi-host: busmaps.com" \
"https://capi.busmaps.com:8443/v1/photon/api?q=London&limit=5"Popular parameters
curl -H "capi-key: Bearer YOUR_API_KEY" \
-H "capi-host: busmaps.com" \
"https://capi.busmaps.com:8443/v1/photon/api?q=London&lat=51.5074&lon=-0.1278&limit=5&lang=en&zoom=16&location_bias_scale=0.2&bbox=-0.51,51.28,0.33,51.69&layer=city&osm_tag=tourism:hotel"Response Example
{
"features": [
{
"geometry": {
"coordinates": [
-0.1277653,
51.5074456
],
"type": "Point"
},
"properties": {
"country": "United Kingdom",
"countrycode": "GB",
"extent": [
-0.5103751,
51.6918741,
0.3340155,
51.2867601
],
"name": "London",
"osm_id": 175342,
"osm_key": "place",
"osm_type": "R",
"osm_value": "city",
"state": "England",
"type": "city"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
-81.2496068,
42.9836747
],
"type": "Point"
},
"properties": {
"country": "Canada",
"countrycode": "CA",
"county": "Southwestern Ontario",
"extent": [
-81.3906556,
43.0730461,
-81.1070784,
42.8245667
],
"name": "London",
"osm_id": 7485368,
"osm_key": "place",
"osm_type": "R",
"osm_value": "city",
"state": "Ontario",
"type": "city"
},
"type": "Feature"
},
{
"geometry": {
"coordinates": [
-0.1164509,
51.5146063
],
"type": "Point"
},
"properties": {
"city": "London",
"country": "United Kingdom",
"countrycode": "GB",
"district": "Covent Garden",
"extent": [
-0.11887,
51.5158628,
-0.1143006,
51.5132068
],
"locality": "St Clement Danes",
"name": "London School of Economics and Political Science",
"osm_id": 4124110,
"osm_key": "amenity",
"osm_type": "R",
"osm_value": "university",
"postcode": "WC2A 2AE",
"state": "England",
"street": "Houghton Street",
"type": "house"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}Response Schema
View JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Photon Forward Geocoding Response",
"type": "object",
"properties": {
"features": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "GeoJSON object type: Feature"
},
"properties": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name"
},
"locality": {
"type": "string",
"description": "Sub-district / quarter / named area within a district"
},
"osm_type": {
"type": "string",
"description": "OSM element type letter: N (node), W (way), R (relation)"
},
"state": {
"type": "string",
"description": "State or region name"
},
"postcode": {
"type": "string",
"description": "Postal code"
},
"osm_key": {
"type": "string",
"description": "OSM key (e.g., place, highway, building, amenity)"
},
"countrycode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code"
},
"country": {
"type": "string",
"description": "Country name"
},
"name": {
"type": "string",
"description": "Name of the place"
},
"district": {
"type": "string",
"description": "District or neighborhood"
},
"housenumber": {
"type": "string",
"description": "House number (for house-type results)"
},
"type": {
"type": "string",
"description": "OSM place type such as city, street, or house"
},
"extent": {
"type": "array",
"items": {
"type": "number"
},
"description": "Bounding box of the feature in [minLon, maxLat, maxLon, minLat] order, in decimal degrees"
},
"osm_id": {
"type": "integer",
"description": "OpenStreetMap element ID"
},
"osm_value": {
"type": "string",
"description": "OSM value (e.g., city, residential, hotel)"
},
"county": {
"type": "string",
"description": "County name"
},
"street": {
"type": "string",
"description": "Street name"
}
},
"required": [
"type",
"osm_type",
"osm_key",
"countrycode",
"osm_id",
"osm_value",
"country",
"name"
],
"description": "Place attributes (fields vary by result type)"
},
"geometry": {
"type": "object",
"properties": {
"coordinates": {
"type": "array",
"items": {
"type": "number"
},
"description": "Coordinate pair in [longitude, latitude] order, in decimal degrees"
},
"type": {
"type": "string",
"description": "GeoJSON geometry type: Point"
}
},
"required": [
"coordinates",
"type"
],
"description": "GeoJSON Point geometry with [lon, lat] coordinates"
}
},
"required": [
"geometry",
"properties",
"type"
]
},
"description": "Array of matching places as GeoJSON Features"
},
"type": {
"type": "string",
"description": "GeoJSON object type: FeatureCollection"
}
},
"required": [
"features",
"type"
]
}Response Codes
200
Search completed successfully (may return empty features array)400
Invalid parameters500
Upstream Photon error or invalid JSON