Photon reverse geocoding – convert coordinates to address

GET /photon/reverse

Reverse geocoding using Photon (Komoot). Returns the nearest OSM object as a GeoJSON FeatureCollection. The nearest object may be a street, building or POI, not necessarily a house address. The endpoint is a pass-through to the upstream Photon instance, so any Photon parameter is forwarded as-is; only the parameters most relevant to typical use are documented here.

Parameters

Parameter	Type	Required	Description	Example
`lat`	number	✓	Latitude coordinate	`51.5`
`lon`	number	✓	Longitude coordinate	`-0.1`
`lang`	string		Response language (e.g., en, de, fr, it, ru)	`en`

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/reverse?lat=51.5&lon=-0.1"

Localized response

curl -H "capi-key: Bearer YOUR_API_KEY" \
     -H "capi-host: busmaps.com" \
     "https://capi.busmaps.com:8443/photon/reverse?lat=51.5&lon=-0.1&lang=en"

Response Example

HTTP 200 - Success

{
  "features": [
    {
      "geometry": {
        "coordinates": [
          -0.0998967,
          51.5001944
        ],
        "type": "Point"
      },
      "properties": {
        "city": "London",
        "country": "United Kingdom",
        "countrycode": "GB",
        "district": "Elephant and Castle",
        "extent": [
          -0.1002233,
          51.5004093,
          -0.099547,
          51.5000175
        ],
        "name": "Belvedere Buildings",
        "osm_id": 31765736,
        "osm_key": "highway",
        "osm_type": "W",
        "osm_value": "cycleway",
        "postcode": "SE1 0DQ",
        "state": "England",
        "type": "street"
      },
      "type": "Feature"
    }
  ],
  "type": "FeatureCollection"
}

Response Schema

Title: Photon Reverse Geocoding Response

View Full JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Photon Reverse 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"
              },
              "state": {
                "type": "string",
                "description": "State/region"
              },
              "osm_type": {
                "type": "string",
                "description": "OSM element type letter: N (node), W (way), R (relation)"
              },
              "postcode": {
                "type": "string",
                "description": "Postal code"
              },
              "osm_key": {
                "type": "string",
                "description": "OSM key (e.g., place, highway, building)"
              },
              "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., residential, cycleway, footway)"
              },
              "street": {
                "type": "string",
                "description": "Street name"
              }
            },
            "required": [
              "city",
              "type",
              "state",
              "osm_type",
              "postcode",
              "osm_key",
              "countrycode",
              "osm_id",
              "osm_value",
              "country",
              "district"
            ],
            "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 containing the nearest matching OSM object as a GeoJSON Feature"
    },
    "type": {
      "type": "string",
      "description": "Type discriminator for the object"
    }
  },
  "required": [
    "features",
    "type"
  ]
}

Response Codes

HTTP 200

Reverse geocoding completed successfully

HTTP 400

Invalid coordinates

HTTP 500

Upstream Photon error or invalid JSON