API Documentation

ChibiGeo is a geocoding and reverse geocoding API based on OpenStreetMap data, built on top of Photon. It converts addresses into geographic coordinates (latitude and longitude) and vice versa, and is Photon-compatible — most Photon clients work by simply pointing them at ChibiGeo.

• Base URL: https://app.chibigeo.com/v1/photon
• Format: every endpoint returns GeoJSON (FeatureCollection).

Features

• Geocoding — convert an address or place name into geographic coordinates.
• Reverse geocoding — convert geographic coordinates into a human-readable place.

Authentication

Every geocoding request must include your API key. You can pass it in either of two headers:

X-Api-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

If both are present, X-Api-Key takes precedence. The /status endpoint is public and needs no key.

Geocoding

Convert a human-readable address or place name into geographic coordinates.

GET https://app.chibigeo.com/v1/photon/api

Parameter	Required	Description
q	yes	The search query (address or place name).
limit	no	Maximum number of results.
lang	no	Language for the results (e.g. en, de).
lat, lon	no	Bias results toward this location.
zoom, location_bias_scale	no	Tune how strongly the location bias is applied.
bbox	no	Restrict results to a bounding box (minLon,minLat,maxLon,maxLat).
layer	no	Restrict to a feature layer (e.g. house, street, city).
osm_tag	no	Filter by OSM tag (e.g. tourism:attraction).
dedupe	no	Deduplicate results.

Example Request

curl 'https://app.chibigeo.com/v1/photon/api?q=Brandenburger+Tor,+Berlin&limit=1' \
  --header 'X-Api-Key: YOUR_API_KEY'

Example Response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "osm_type": "W",
        "osm_id": 518071791,
        "osm_key": "tourism",
        "osm_value": "attraction",
        "type": "house",
        "housenumber": "1",
        "name": "Brandenburger Tor",
        "street": "Pariser Platz",
        "locality": "Friedrich-Wilhelm-Stadt",
        "district": "Mitte",
        "city": "Berlin",
        "country": "Deutschland",
        "postcode": "10117",
        "countrycode": "DE",
        "extent": [13.3775798, 52.5164328, 13.3778251, 52.516117]
      },
      "geometry": {
        "type": "Point",
        "coordinates": [13.3777034, 52.5162699]
      }
    }
  ]
}

Reverse Geocoding

Convert geographic coordinates into a human-readable place.

GET https://app.chibigeo.com/v1/photon/reverse

Parameter	Required	Description
lat	yes	Latitude.
lon	yes	Longitude.
limit	no	Maximum number of results.
lang	no	Language for the results (e.g. en, de).
radius	no	Search radius.
layer	no	Restrict to a feature layer (e.g. house, street, city).
osm_tag	no	Filter by OSM tag.
dedupe	no	Deduplicate results.

Example Request

curl 'https://app.chibigeo.com/v1/photon/reverse?lat=52.5162&lon=13.3778' \
  --header 'X-Api-Key: YOUR_API_KEY'

Example Response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "osm_type": "W",
        "osm_id": 518071791,
        "osm_key": "tourism",
        "osm_value": "attraction",
        "name": "Brandenburger Tor",
        "housenumber": "1",
        "street": "Pariser Platz",
        "district": "Mitte",
        "city": "Berlin",
        "postcode": "10117",
        "country": "Deutschland",
        "countrycode": "DE"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [13.3777034, 52.5162699]
      }
    }
  ]
}

Status

A public health check — no API key required.

curl 'https://app.chibigeo.com/v1/photon/status'

{ "import_date": "2025-11-02T00:01:55Z", "status": "Ok" }

Errors

Errors are returned as JSON with an error field and the matching HTTP status code.

Status	error	Meaning
401	missing_api_key	No API key was provided in the request headers.
401	invalid_api_key	The API key was not recognized.
429	limit_exceeded	You've hit your plan's request cap. The free plan resets daily at 00:00 UTC; paid plans reset at the start of next month.
503	upstream_unavailable	The geocoding backend is temporarily unavailable.
504	upstream_timeout	The geocoding backend took too long to respond.