Skip to main content

Hosted Photon geocoding for GeoPulse

GeoPulse is a self-hosted, privacy-first location timeline platform with built-in support for Photon reverse geocoding. ChibiGeo is a hosted Photon endpoint — flat-rate, EU-only, hard-capped — that GeoPulse's Photon provider talks to natively.

GeoPulse's Photon provider has no separate API-key field, so you carry your ChibiGeo key in the base URL as a path segment. No GeoPulse changes needed.

Prerequisites​

  • A running GeoPulse instance.
  • A ChibiGeo API key (ck_…). The Self-Hoster plan (€9.99/mo) covers supported self-hosted apps like GeoPulse. Get one at app.chibigeo.com.

Configuration​

Set GeoPulse's geocoding environment variables (in your .env or the geopulse-backend service's environment: block):

GEOPULSE_GEOCODING_PRIMARY_PROVIDER=photon
GEOPULSE_GEOCODING_PHOTON_ENABLED=true
GEOPULSE_GEOCODING_PHOTON_URL=https://app.chibigeo.com/v1/photon/ck_your_key_here
VariableValueWhy
GEOPULSE_GEOCODING_PRIMARY_PROVIDERphotonUse Photon (ChibiGeo) as the geocoder
GEOPULSE_GEOCODING_PHOTON_ENABLEDtrueEnable the Photon provider
GEOPULSE_GEOCODING_PHOTON_URLhttps://app.chibigeo.com/v1/photon/ck_your_key_hereBase URL with your key as the last path segment

The key is part of the base URL. GeoPulse appends /reverse (or /api) to it, so it sends:

GET https://app.chibigeo.com/v1/photon/ck_your_key_here/reverse?lon=…&lat=…

ChibiGeo reads the key from the path, authenticates, and returns the address. Restart the geopulse-backend container to apply the change.

You can also set these under Admin → Settings → Geocoding if you prefer the UI over environment variables.

Verifying it works​

Confirm the endpoint from a shell first:

curl "https://app.chibigeo.com/v1/photon/ck_your_key_here/reverse?lon=13.377&lat=52.516"

A GeoJSON FeatureCollection with populated properties (name, city, country) means the key and URL are right. In GeoPulse, once significant places are detected they'll be reverse-geocoded through ChibiGeo; you can re-run geocoding from the Reverse Geocoding Management page.

Troubleshooting​

SymptomCauseFix
401 invalid_api_keyWrong key in the base URLRe-copy the key; ensure the URL ends with /v1/photon/<key>
401 missing_api_keyKey segment missingGEOPULSE_GEOCODING_PHOTON_URL must be …/v1/photon/<key>, not just …/v1/photon
429Monthly cap reachedChibiGeo hard-caps rather than billing overage — raise the plan
Still using NominatimProvider not switchedSet GEOPULSE_GEOCODING_PRIMARY_PROVIDER=photon and restart

Why ChibiGeo​