Reverse Geocoding
GeoPulse uses geocoding services to convert GPS coordinates into human-readable addresses and location names. You can configure multiple providers with automatic fallback support. This configuration applies to all users.
Overall Geocoding Configuration
| Property | Default | Description |
|---|---|---|
GEOPULSE_GEOCODING_DELAY_MS | 1000 | A delay in milliseconds between sending requests to geocoding provider. Nomatim's default rate limit is 1req/s. For selfhosted solutions change it to lower value |
Available Providers
| Provider | Free Tier | API Key Required | Rate Limits |
|---|---|---|---|
| Nominatim | Yes | No | 1 request/second |
| Photon | Yes | No | Unknown |
| Google Maps | Limited | Yes | 40,000 requests/month free |
| Mapbox | Limited, see ToS note below | Yes | 100,000 requests/month free |
Geocoding Configuration
| Property | Default | Description |
|---|---|---|
GEOPULSE_GEOCODING_PRIMARY_PROVIDER | nominatim | Primary geocoding service (nominatim, googlemaps, mapbox, photon) |
GEOPULSE_GEOCODING_FALLBACK_PROVIDER | (empty) | Fallback service if primary fails |
GEOPULSE_GEOCODING_NOMINATIM_ENABLED | true | Enable Nominatim geocoding service |
GEOPULSE_GEOCODING_NOMINATIM_URL | https://nominatim.openstreetmap.org | Nominatim url |
GEOPULSE_GEOCODING_PHOTON_ENABLED | false | Enable Photon geocoding service |
GEOPULSE_GEOCODING_PHOTON_URL | https://photon.komoot.io | Photon url |
GEOPULSE_GEOCODING_GOOGLE_MAPS_ENABLED | false | Enable Google Maps geocoding service |
GEOPULSE_GEOCODING_GOOGLE_MAPS_API_KEY | (empty) | Google Maps API key (required for Google Maps) |
GEOPULSE_GEOCODING_MAPBOX_ENABLED | false | Enable Mapbox geocoding service |
GEOPULSE_GEOCODING_MAPBOX_ACCESS_TOKEN | (empty) | Mapbox access token (required for Mapbox) |
Service Setup
Nominatim (Default)
- No API key required
- Uses OpenStreetMap data
- Rate limited to 1 request per second
- Best for privacy-conscious users
- Possible to use self-hosted version
Photon
- No API key required
- Rate limited to 2 request per second
- Possible to use self-hosted version
Google Maps
- Get API key from Google Cloud Console
- Enable Geocoding API
- Set billing account (free tier available)
Mapbox
- Create account at Mapbox
- Generate access token
- Monitor usage in dashboard
⚖️Terms of Service & Free Tier Notice for Mapbox
Mapbox usage in this app is optional and requires your own access token.
By providing a Mapbox token, you agree to the Mapbox Terms of Service and are responsible for complying with them, including any usage, caching, or data-storage restrictions.
The Mapbox free tier includes a limited number of monthly requests and is intended for development and light personal use.
If you exceed those limits or need to store geocoding results long-term — for example, saving reverse-geocoded addresses in your database (which this app does by default) — you may need a paid or commercial plan that supports permanent data storage.
Geocoding Environment Variables
# Geocoding Service Configuration
GEOPULSE_GEOCODING_PRIMARY_PROVIDER=nominatim
GEOPULSE_GEOCODING_FALLBACK_PROVIDER=googlemaps
# Service Enablement
GEOPULSE_GEOCODING_NOMINATIM_ENABLED=true
GEOPULSE_GEOCODING_GOOGLE_MAPS_ENABLED=true
GEOPULSE_GEOCODING_MAPBOX_ENABLED=false
# Custom URLs
GEOPULSE_GEOCODING_NOMINATIM_URL=https://nominatim.openstreetmap.org
GEOPULSE_GEOCODING_PHOTON_URL=https://photon.komoot.io
# API Credentials (if using paid services)
GEOPULSE_GEOCODING_GOOGLE_MAPS_API_KEY=your_google_api_key_here
GEOPULSE_GEOCODING_MAPBOX_ACCESS_TOKEN=your_mapbox_token_here
#Delay between requests to geocoding provider
GEOPULSE_GEOCODING_DELAY_MS=1000