Photon forward geocoding – search locations by name

GET /photon/api

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.

Parameters

Parameter	Type	Required	Description	Example
`q`	string	✓	Search query, supports partial/prefix input for autocomplete	`London`
`lat`	number		Latitude for location bias (soft boost, not a hard filter)	`51.5074`
`lon`	number		Longitude for location bias (soft boost, not a hard filter)	`-0.1278`
`limit`	integer		Maximum number of results to return Default: 15	`5`
`lang`	string		Response language (e.g., en, de, fr, it, ru)	`en`
`zoom`	integer		Map zoom level hint for search radius Default: 16	`16`
`location_bias_scale`	number		Strength of location bias from 0.0 to 1.0 Default: 0.2	`0.2`
`bbox`	string		Bounding box hard filter in 'minLon,minLat,maxLon,maxLat' format	`-0.51,51.28,0.33,51.69`
`layer`	string		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		OSM tag filter. Use 'key:value' to include or '!key' to exclude	`tourism:hotel`

Try It Out

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

Example Requests:

Required parameters only

curl -H "capi-key: Bearer YOUR_API_KEY" \
     -H "capi-host: busmaps.com" \
     "https://capi.busmaps.com:8443/photon/api?q=London"

Autocomplete with location bias

curl -H "capi-key: Bearer YOUR_API_KEY" \
     -H "capi-host: busmaps.com" \
     "https://capi.busmaps.com:8443/photon/api?q=Lond&lat=51.5074&lon=-0.1278&limit=5&lang=en"

Filter by layer and OSM tag

curl -H "capi-key: Bearer YOUR_API_KEY" \
     -H "capi-host: busmaps.com" \
     "https://capi.busmaps.com:8443/photon/api?q=hotel&layer=street&layer=house&osm_tag=tourism:hotel&bbox=-0.51,51.28,0.33,51.69"

Response Example

HTTP 200 - Success

{
  "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

Title: Photon Forward Geocoding Response

View Full 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": "Type discriminator for the object"
          },
          "properties": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "City"
              },
              "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/region"
              },
              "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": "Display name"
              },
              "district": {
                "type": "string",
                "description": "District"
              },
              "housenumber": {
                "type": "string",
                "description": "House number (for house-type results)"
              },
              "type": {
                "type": "string",
                "description": "Type discriminator for the object"
              },
              "extent": {
                "type": "array",
                "items": {
                  "type": "number"
                },
                "description": "Bounding box of the feature in [minLon, maxLat, maxLon, minLat] order"
              },
              "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"
              },
              "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 [lon, lat] order"
              },
              "type": {
                "type": "string",
                "description": "Type discriminator for the object"
              }
            },
            "required": [
              "coordinates",
              "type"
            ],
            "description": "Encoded route geometry"
          }
        },
        "required": [
          "geometry",
          "properties",
          "type"
        ]
      },
      "description": "Array of matching places as GeoJSON Features"
    },
    "type": {
      "type": "string",
      "description": "Type discriminator for the object"
    }
  },
  "required": [
    "features",
    "type"
  ]
}

Response Codes

HTTP 200

Search completed successfully (may return empty features array)

HTTP 400

Invalid parameters

HTTP 500

Upstream Photon error or invalid JSON