Geocoding Rate Limits and Caching

This article closes the recommended trio of Geocoding Deep Dives with operational concerns: how to use geocoding APIs reliably and economically at production scale. Companion to /learn/mapbox-geocoding-vs-google-vs-here (provider comparison) and /learn/nominatim-explained (self-hosted alternative).

Rate limits across providers

Rate limits constrain how many requests you can issue per second, minute, or month. Exceeding limits results in HTTP 429 (Too Many Requests) responses that your application must handle gracefully.

Mapbox v6

• Free tier default: ~600 requests per minute (~10 req/sec) burst; sustained throughput limited by the 100,000-per-month quota.
• Paid plans: higher per-minute and per-month limits.
• Enterprise: negotiated limits.

Mapbox returns 429 with Retry-After header on rate-limit hits.

Google Maps Geocoding

• Default QPS: ~50 queries per second for active billing accounts.
• Per-day quota: configurable via Google Cloud Console (subject to billing).
• Per-month quota: configurable.

Google's quota system is hierarchical: per-second, per-day, per-month. Hitting any limit returns an OVER_QUERY_LIMIT status.

HERE Geocoding

• Freemium tier: 250,000 transactions/month, no specific per-second limit (subject to fair-use).
• Paid plans: monthly quotas vary.
• Enterprise: negotiated.

HERE's freemium is one of the most generous.

OSM Nominatim public service

• Strict 1 request per second per IP.
• No batch processing.
• User-Agent header required.
• Attribution required.

The public service is for development and small projects only.

Self-hosted Nominatim

• Limited only by hardware.
• Typical: 10-100 req/sec on commodity hardware.
• No artificial limits.

Self-hosting eliminates rate-limit concerns at the cost of operational overhead.

Caching policies

The major split: Mapbox forbids caching; Google and HERE allow 30-day caching; Nominatim encourages caching.

Mapbox: no retention

Mapbox's Terms of Service explicitly forbid retention of geocoding response data:

“You may not store or cache the geocoding response data...”

For Coordinately, this means (per arch decision §19.2):

• Per-request SSR is compatible: the server renders a Mapbox response into the page and serves it. The user receives the data; no retention occurs on the server side.
• Persistent caching is forbidden: no Redis cache, no database table of geocoded addresses.
• Pre-baking static address tables is forbidden.

Operational implication: every user query hits the Mapbox API. Costs scale linearly with query volume.

Google: 30-day caching

Google's Terms allow caching of lat, lng, and place_id for up to 30 days:

• Store the canonical fields for up to 30 days.
• Re-query within 30 days to refresh.
• The exact restrictions on what to cache are detailed in Google's API Terms.

Operational implication: applications with repeating queries can dramatically reduce costs through caching. E-commerce, registered users, and batch-imported address lists all benefit.

HERE: ~30-day caching

HERE typically permits 30-day caching, with specifics varying by plan. Enterprise plans may have different (often more permissive) terms.

Esri ArcGIS

Caching terms depend on the license plan; enterprise plans often have no specific limit.

OSMF Nominatim public service

Caching is encouraged to reduce server load. Self-hosted Nominatim has no policy restrictions — cache as you like.

Session-token billing

For autocomplete UX, providers offer session tokens that significantly reduce billing cost.

The problem

A user types “Empire State Building” letter by letter:

E         → autocomplete query
Em        → autocomplete query
Emp       → autocomplete query
Empi      → autocomplete query
...
Empire State Building     → final selection → geocode

Without session tokens: 22+ billable autocomplete requests for one logical “find a place” session.

Google Places Autocomplete

Google's solution: session tokens. The client generates a unique session ID; all autocomplete requests during the session use the same ID; Google bills only when the user selects a suggestion (or doesn't — sessions have a timeout).

Typical reduction: 5-50× fewer billable requests for autocomplete UX.

Mapbox v6 search sessions

Mapbox v6 has similar session-based billing for search/autocomplete endpoints.

HERE autocomplete

HERE's autocomplete endpoints are typically priced per request at lower cost than full geocoding; session tokens aren't universal but billing is structured to make autocomplete UX economical.

Implementation

Session tokens are client-generated (typically UUIDs):

const sessionToken = crypto.randomUUID();

// Each autocomplete keystroke:
const url =
  `https://api.mapbox.com/search/v1/suggest?` +
  `q=${query}&session_token=${sessionToken}&...`;
fetch(url);

// Final geocode on selection:
const finalUrl =
  `https://api.mapbox.com/search/v1/retrieve?` +
  `id=${selectedId}&session_token=${sessionToken}&...`;
fetch(finalUrl);

The same session_token across all requests in the session is the key.

Batch endpoints

For high-volume geocoding (importing address lists, nightly batch jobs), batch endpoints process many addresses in a single API call.

HERE Batch Geocoding

HERE provides explicit batch endpoints:

• Submit up to 10,000 addresses per request.
• Asynchronous processing (~minutes).
• Results returned in CSV or JSON.
• Per-address cost typically lower than per-query pricing.

Used for: address-list validation, address- standardization runs, periodic data refresh.

Mapbox v6 Batch

Mapbox v6 introduced a batch endpoint:

• Up to 1,000 addresses per request.
• Synchronous (faster than HERE for smaller batches).
• Per-address pricing similar to interactive queries.

Google Geocoding

Google doesn't offer a dedicated batch endpoint — applications must issue individual requests in parallel (subject to QPS limits). This makes Google less suitable for true batch workloads.

Nominatim batch

Self-hosted Nominatim supports batch processing via direct database access (PostgreSQL queries against the Nominatim schema). For large batches, self-hosted Nominatim is dramatically faster than calling the API endpoint for each address.

Operational patterns

Coarse-then-fine

For complex queries, query at the country/region level first to validate the input is a real place, then drill down:

1. User types “Springfield, IL”.
2. Application validates “Springfield, IL” is a real city (one geocoding call).
3. User types specific address.
4. Application geocodes the full address (second call).

Reduces the chance of expensive geocoding calls on typos and invalid inputs.

Type-ahead with deferred full geocoding

The autocomplete pattern:

1. User types into autocomplete field.
2. Each keystroke (after debounce) triggers a lightweight autocomplete request — suggestions only, no full geocoding.
3. User selects a suggestion.
4. Application issues one full geocoding request to retrieve the canonical place data for the selected suggestion.

With session tokens, the autocomplete UX is one billable transaction.

Multi-provider failover

For mission-critical reliability:

def geocode(query):
    try:
        return mapbox_geocode(query)
    except RateLimit:
        return google_geocode(query)
    except Error:
        return here_geocode(query)

Adds complexity (multiple credentials, response- format differences) but provides resilience.

Circuit breaker

If a provider returns repeated errors, stop calling them temporarily:

breaker = CircuitBreaker(
    failure_threshold=5,
    recovery_timeout=60  # seconds
)

@breaker.call
def geocode(query):
    return mapbox_geocode(query)

If 5 consecutive failures occur, the breaker “opens” — subsequent calls fail immediately (or fall back) for 60 seconds, then the breaker tries again. Prevents cascading failures during provider outages.

Exponential backoff

On retryable errors (rate limits, transient network issues), retry with increasing delays:

retry 1: wait 1 second
retry 2: wait 2 seconds
retry 3: wait 4 seconds
retry 4: wait 8 seconds
...

Combined with jitter (random fractional addition) to avoid thundering-herd reconnection patterns.

Monitoring

Track per-day, per-hour, per-minute usage:

• Per-provider request counts.
• Error rate.
• 429 rate-limit responses.
• Average response time.
• Quota approaches (e.g., alert at 80% of monthly quota).

Most providers offer usage dashboards; supplement with application-level monitoring (Prometheus, DataDog, CloudWatch) for finer-grained insight.

API key rotation

For security, rotate API keys periodically:

• Store keys in environment variables or secret managers.
• Rotate every 90-180 days or on staff turnover.
• Test new keys before retiring old ones.
• Monitor for unexpected key usage (security indicator).

PII and privacy

Geocoding queries often contain personally identifiable information (PII):

• Residential addresses.
• Workplace addresses.
• Medical facility addresses.
• Legal proceeding addresses.

Considerations

Vendor data handling: review the geocoder's privacy policy. Even with no-retention rules (Mapbox), the provider may log requests for operational purposes (debugging, abuse detection, analytics).

Regional data sovereignty: EU GDPR may require data residency for European user data. Some providers offer EU-region API endpoints; verify compliance.

Sensitive contexts: medical, legal, victim-of- violence locations may warrant special handling:

• On-premises geocoding (self-hosted Nominatim) eliminates third-party data exposure.
• Aggregation/k-anonymity: report only at larger spatial granularity (city, postal code) rather than precise lat/lon.
• Differential privacy: add deliberate noise to make individual locations unidentifiable.

Compliance

• GDPR (EU): explicit consent for processing PII; right to data deletion.
• CCPA (California): consumer right to know what data is collected.
• HIPAA (US healthcare): special handling for patient location data.
• PCI (payment industry): geocoding billing addresses may have specific requirements.

Verify with legal counsel for compliance-sensitive use cases.

Cost optimization strategies

For applications where geocoding costs matter:

Cache where allowed

For Google and HERE (30-day caching permitted): aggressive caching is the dominant cost optimization. A 30-day cache hit rate of 50% halves the per-month cost.

Use cheaper endpoints

• Mapbox v6 autocomplete vs full geocode: autocomplete is cheaper.
• Google Places Autocomplete with session tokens: reduces billing dramatically.
• HERE batch endpoint vs interactive: bulk pricing is lower.

Pre-geocode known addresses

For applications with known static address sets (employee addresses, store locations), pre-geocode once and store the results. Note: subject to provider caching restrictions.

Multi-provider for cost

Use the cheapest provider as primary (Mapbox or self-hosted Nominatim); escalate to premium providers only for low-confidence cases that need higher accuracy.

Geocoder selection by use case

• High-volume validation: HERE batch or self-hosted Nominatim.
• User-typed addresses: Mapbox v6 autocomplete with session tokens.
• Critical accuracy (legal, financial): Google premium pricing justified.

Monitor and alert

Set up cost alerts:

• Daily spend threshold alerts.
• Anomaly detection for unusual spikes.
• Quota approach alerts (80% of monthly).
• Per-feature cost attribution.

Error handling

Geocoding APIs return various error conditions:

200 OK with empty results

The most common “error”: the query matched no places. Different from a true error; the application should handle it as a UX issue (suggest the user refine the query).

4xx errors

• 400 Bad Request: malformed query.
• 401 Unauthorized: missing or invalid API key.
• 403 Forbidden: API key valid but lacking permission.
• 404 Not Found: invalid endpoint.
• 429 Too Many Requests: rate-limit exceeded.

For 429, respect the Retry-After header (if provided) and apply exponential backoff.

5xx errors

• 500 Internal Server Error.
• 502 Bad Gateway.
• 503 Service Unavailable.
• 504 Gateway Timeout.

For 5xx, retry with backoff; if persistent, activate circuit breaker and fall back to alternative provider.

Network errors

Timeouts, connection failures, DNS errors — handle as transient failures; retry with backoff; fall back if persistent.

Specific Coordinately context

Per CLAUDE.md and architectural decisions:

• §19.1: Mapbox v6 with limit=5; surface low/medium-confidence candidates rather than auto-select.
• §19.2: Mapbox no-retention rule — per-request SSR compatible; caching/pre-baking forbidden.

Operational implications:

• Every user-typed query hits Mapbox.
• Cost scales linearly with traffic.
• Below 100k/month free tier currently.
• Future scaling may require migration to a caching-permitting provider or self-hosted Nominatim — flagged in arch decisions.

Common misconceptions

“Rate limits are easily avoided.” Not at scale. Production applications hitting high QPS need explicit planning: backoff, batching, multi-key strategies, or paid-tier upgrades.

“You can always cache geocoding results.” Depends on the provider. Mapbox forbids it; Google and HERE permit 30-day caching with specific restrictions; self-hosted Nominatim has no restrictions.

“Caching breaks geocoding correctness.” Generally no — for canonical addresses, the geocoding result is stable over months. For new construction or recently-changed addresses, the cached value may be stale; refresh after the cache TTL.

“429 errors are bugs.” No — they're expected operational signals. Handle gracefully with backoff and user-facing “try again in a moment” messaging.

“Session tokens are mandatory.” No — they're a billing optimization specific to certain providers (Google, Mapbox v6). Without them, autocomplete UX is billable per keystroke. Use them when supported and applicable.

“Self-hosted Nominatim eliminates all operational concerns.” Reduces but doesn't eliminate. Self-hosting moves the operational burden in-house: database administration, monitoring, updates, capacity planning. Trade-off is third-party-vendor dependency vs in-house operational responsibility.

“Geocoding queries are not sensitive.” Often they are. User addresses can be highly sensitive depending on context (medical, legal, vulnerable populations). Plan privacy and data-handling appropriately.

“Multi-provider failover doesn't add complexity.” It does: multiple credentials, response-format differences, billing across multiple providers, monitoring complexity. Use when reliability requirements justify the complexity.

“Circuit breakers are overkill.” For critical applications, they're essential. A provider outage can cascade into your application's degradation; circuit breakers contain the damage.

“Cost is the only optimization metric.” Also: latency, reliability, privacy, operational complexity. The cheapest provider isn't always the right one.

“Free tiers are sustainable indefinitely.” Plan for paid usage. Free tiers are typically promotional; production applications eventually exceed them. Budget for paid usage from the start.

“Batch geocoding is rare.” Common in many contexts: e-commerce address validation, fleet/logistics planning, marketing analytics, real-estate listings. HERE's explicit batch endpoint reflects this demand.

“Geocoding always returns one answer.” It returns ranked candidates. Coordinately's arch §19.1 explicitly surfaces low-confidence candidates; production systems should similarly avoid auto-selecting low-confidence results.