Home
Developers
Voice Model-Ready Endpoints
Search Photon for voice agents

Search Photon for voice agents

GET /compact/v1/photon/api

Base URL: https://capi.busmaps.com:8443

For voice models and voice agents, this endpoint reduces response tokens and keeps spoken-answer tool calls focused. Search Photon with the same query parameters and result order as /v1/photon/api, then return every matching place in the same compact positional format as the Compact API Nominatim search. resultFields defines the columns in each results row. The response keeps the short name, a full human-readable label assembled from Photon address components, place type, country code and coordinates. Provider-specific GeoJSON wrappers, OSM identifiers and bounds are omitted. Repeated parameters such as layer=street&layer=house are preserved.

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.

Need the complete response object?

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, 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 (Default: 15)	`5`
`lang`	string	No	Response language supported by Photon; omit for its default language (Values: de, en, fr)	`en`
`zoom`	integer	No	Map zoom level hint for search radius (Default: 16)	`16`
`location_bias_scale`	number	No	Strength of location bias from 0.0 to 1.0 (Default: 0.2)	`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) (Values: house, street, locality, district, city, county, state, country, other)	`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/compact/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/compact/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/compact/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

{
    "resultFields": [
        "name",
        "label",
        "type",
        "countryCode",
        "lat",
        "lon"
    ],
    "results": [
        [
            "London",
            "London, England, United Kingdom",
            "city",
            "GB",
            51.5074456,
            -0.1277653
        ],
        [
            "London",
            "London, Southwestern Ontario, Ontario, Canada",
            "city",
            "CA",
            42.9836747,
            -81.2496068
        ],
        [
            "London School of Economics and Political Science",
            "London School of Economics and Political Science, Houghton Street, St Clement Danes, Covent Garden, London, England, WC2A 2AE, United Kingdom",
            "house",
            "GB",
            51.5146063,
            -0.1164509
        ]
    ]
}

Response Schema

View JSON Schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Compact Photon 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 Photon"
        }
    },
    "required": [
        "resultFields",
        "results"
    ]
}

Response Codes

200 Search completed successfully (results may be empty)

400 Invalid parameters

500 Photon service error or invalid JSON