Compliance: persisting provider responses

gotime talks to commercial map/routing APIs. Most vendors’ Terms of Service restrict — or outright forbid — long-term storage of their raw responses. This page documents the posture we’ve adopted and the knobs you can turn.

This page is an operator-facing summary written in April 2026 and is not legal advice. Always confirm against the vendor’s current ToS, AUP, and Data Processing Agreement before relying on it in production. Links to the authoritative documents are included below.

Default behaviour

  • Normalized trips — trips rows (duration, distance, steps, …) are always written. The normalized view is derived data about your own routes and is what the dashboards and statistics use.

  • Raw provider JSON — trip_api_logs.raw_json is not written by default. Turning it on requires an explicit opt-in:

    • Environment: GOTIME_STORE_RAW_RESPONSES=true (truthy values: 1, true, yes, on, case-insensitive).

    • Programmatic: persist_trip(session, result, store_raw=True) — the kwarg overrides the environment and is useful in tests.

The opt-in is intentional: several providers below explicitly prohibit the kind of persistence a naïve raw_json column represents.

Per-provider summary

Provider

Raw-response storage

Cap

Notes

Google Maps Platform

Restricted

Lat/lon ≤ 30 days; Place IDs indefinite

Caching limits live in the Directions API policies and Service Specific Terms. Full response payloads are effectively not permitted long-term.

Mapbox

Prohibited

n/a

The Mapbox Terms of Service state “you may not cache, store, or export any map content from the Services.” Do not flip the opt-in on for Mapbox without a separate commercial agreement.

Bing Maps

Prohibited

n/a

The Bing Maps End User ToS forbid copying, caching, or retaining maps, routes, images, or other data provided by the service.

Azure Maps

Restricted (latency cache only)

shorter of header TTL or 6 months

See the Azure Maps product terms and the Microsoft Q&A on caching policy. Storage is allowed only to reduce application latency, not to redistribute or re-use across users.

TomTom

Unclear from public docs

—

See the TomTom Developer ToC and the data residency FAQ. Developer/Freemium plans generally do not grant long-term storage rights; confirm with TomTom support if you need it.

HERE

Unclear from public docs

—

See the HERE Platform Terms and the Acceptable Use Policy / Data Processing Agreement linked from it. Freemium plans typically forbid long-term storage of raw responses.

MapQuest

Standard plan restricted; Extended Rights available

—

See the MapQuest Terms of Use and the Extended Rights Geocoding add-on. Directions persistence rules are not spelled out publicly; conservative default is “don’t store”.

If you opt in

When you turn on GOTIME_STORE_RAW_RESPONSES, consider:

  1. Scope it per provider. If some of your providers forbid storage, route their calls through a separate gotime instance (or a custom fork of persist_trip) with the flag off. The built-in toggle is process-wide, not per-provider.

  2. Implement a retention job. The tightest common cap is Google’s 30-day lat/lon rule. A weekly job such as

    DELETE FROM trip_api_logs WHERE timestamp < NOW() - INTERVAL '30 days';

    keeps you inside that envelope. The normalized trips table is untouched.

  3. Re-check annually. Vendor terms change. The links in the table above are authoritative; the matrix is just a human-readable index.