Geocoding

TimeTiles geocodes text addresses into map coordinates during imports. The default provider seed includes three enabled public endpoints that do not require API keys. Existing installations may have different provider settings.

How It Works

When you import a file with address data (e.g., “Berlin, Germany”), TimeTiles:

1. Collects unique normalized locations from the file before looking them up
2. Checks the location cache for previously geocoded addresses
3. Distributes uncached addresses across configured providers
4. Stores results for event creation

Cached results are reused for 30 days by default. Cache hits avoid provider requests, but the rest of the import pipeline still runs. Retries and fallback can require multiple requests for an uncached address.

Providers

Configure providers at /dashboard/collections/geocoding-providers.

Public Endpoints (enabled in the default seed)

These values configure TimeTiles’ request pacing and distribution; they are not provider quotas or guaranteed throughput. Actual duration depends on latency, cache hits, retries, provider availability, and worker load.

API-Key Providers

These are TimeTiles’ fallback rate settings for providers without an explicit rate limit, not account quotas. Configure API keys and limits appropriate to your account at /dashboard/collections/geocoding-providers.

Weighted Distribution

During batch geocoding (imports), the highest-priority available provider determines the active group. Providers in that group share requests proportional to their rateLimit setting. An ungrouped provider handles primary requests alone; remaining providers are fallback candidates.

Default configuration:

• VersaTiles (rateLimit: 30, group: "photon") gets ~75% of requests
• Komoot (rateLimit: 10, group: "photon") gets ~25%
• Nominatim (no group) is a fallback candidate; it can also become primary when both Photon providers are in backoff

Adjust the rateLimit values in the admin panel to change the distribution. For example, setting both Photon providers to rateLimit: 10 gives each 50%.

For single-address calls to the geocoding service, providers are tried sequentially by priority.

With Fallback enabled switched off, a failed or invalid result does not trigger requests to another provider, in either single-address or batch geocoding. Retrying a transient failure on the selected provider is independent of this setting.

Throttling and Resilience

The system handles rate limiting automatically:

• 429 (Too Many Requests): Retries once after exponential backoff, then tries another provider if fallback is enabled
• 502/503/504 (gateway errors or service unavailable): Same retry + fallback behavior
• 404 from Photon: Treated as throttle signal (Photon returns 200 with empty results for genuine “not found”)
• Retry-After header: Numeric seconds are used for 429 responses. HTTP-date values are not parsed; the normal backoff applies instead.

Backoff escalates: 2s → 4s → 8s → 16s → max 30s on consecutive throttles. Resets on success.

If a provider is in backoff, it is temporarily skipped — requests go to available providers instead. If all providers are in backoff, the request waits for the soonest-available provider.

Geographic Filtering

All settings are configured once per provider — the system maps them to each provider’s API automatically.

Language

Set the Language field (ISO 639-1 code, e.g., de) to get results in the preferred language. Supported by all providers.

Country Codes

Set Country Codes (comma-separated ISO 3166-1 alpha-2, e.g., de,at,ch) to restrict or bias results to specific countries. Supported by all providers.

Location Bias

Bias results towards a geographic center point. Results outside the bias area still appear, but are ranked lower.

• Latitude / Longitude: Center point
• Zoom level (Photon only): 1 (world) to 18 (building). Controls bias radius. Default: 10

Example: For a German dataset, set bias to lat: 51.1, lon: 10.4, zoom: 5 to prefer German results for ambiguous addresses like “Frankfurt”.

How it maps per provider:

• Photon: lat, lon, zoom query parameters
• OpenCage: proximity=lat,lon parameter
• Nominatim / LocationIQ: viewbox centered on the bias point
• Google: region country code from Country Codes field

Bounding Box

Set Min/Max Longitude and Latitude to request a bounding-box filter from supported providers. The Google integration does not apply this box.

How it maps per provider:

• Photon: bbox parameter
• OpenCage: bounds parameter
• Nominatim: viewbox + bounded=1 constructor options
• LocationIQ: viewbox + bounded=1 query parameters
• Google: No bounding-box parameter is sent; region comes from Country Codes and is not a hard geographic filter

Photon-Only Filters

These are specific to Photon and configured in the provider-specific settings:

• Layer filter: Restrict to geographic layers (house, street, city, state, country). Useful for avoiding street-level noise when geocoding city names.
• OSM tag filter: Filter by OpenStreetMap tags (place:city, !highway, :!construction).

Global Settings

Configure at /dashboard/globals/settings under the Geocoding section:

Caching

The location cache (/dashboard/collections/location-cache) stores geocoded results:

• Addresses are normalized before lookup (lowercased, whitespace collapsed, special characters stripped)
• Cache hits increment a counter and update the “last used” timestamp
• TTL is measured from creation, not the last cache hit; frequent use does not extend it
• When caching is enabled, expired entries are removed on lookup and by the cache-cleanup job every six hours. The ingest worker must run with --handle-schedules, as configured in the production Compose stack
• Admins can manually delete cache entries to force re-geocoding

Adding a Provider

1. Go to /dashboard/collections/geocoding-providers
2. Click Create New
3. Select the provider type, enter a name, and set priority and rate limit
4. Configure provider-specific settings (API key, location bias, etc.)
5. Set group if you want the provider to share batch work with others
6. Enable the provider
7. Test with the geocoding test panel on the provider list page

Self-Hosting Photon

For high-volume or private use, you can run your own Photon instance:

1. Follow the Photon setup guide 
2. Create a new Photon provider in the admin panel
3. Set the Base URL to your instance (e.g., http://photon:2322)
4. Set rateLimit to a value your instance can sustain
5. Optionally disable the public Photon providers