Data APIdocs

Freshness and versions

This page answers two practical questions: how fresh is the data I'm getting and how do I detect when it's changed? Both matter if you're caching results client-side, building SLAs around the API, or trying to explain why a number moved.

Per-country snapshots

The platform rebuilds country datasets on a schedule. A rebuild is atomic from a customer's perspective: a new snapshot is built end-to-end on a separate path, then swapped in once it's complete. There's no window where you see half-old, half-new data.

Each snapshot carries the build timestamp it was stamped with. The API exposes it as last_refreshed in the response from GET /v1/stats?country=<cc>, alongside the dataset counts — see the Quickstart for an example response.

last_refreshed is the canonical "what snapshot am I reading" signal. If your client caches results by location or by isochrone, the right cache key includes this value. It is null on an index built before the timestamp was stamped, and the public-transport layer carries its own separate data_version on GET /v1/pt/meta.

Rebuild cadence

The default rebuild schedule is monthly per country, with new-country first builds running on-demand. Why monthly:

  • POI sources update on slower cadences than this. Foursquare publishes their open dataset roughly quarterly. OSM streams continuously but the practical refresh cycle is weeks. Overture publishes monthly.
  • Transport timetables shift seasonally. Major operators publish service-pattern changes a few times a year; bus operator timetables shift more frequently. A monthly refresh catches most timetable revisions inside a calendar year.
  • Polygon land-cover is structurally stable. Park boundaries don't move; new developments take years to show up on Overture. Monthly is overkill for polygons but fine on cost.

In practice, a country's snapshot is usually 1–4 weeks old. The last_refreshed timestamp in /v1/stats tells you exactly.

What changes between rebuilds

Not all rebuilds change all the things. A typical month-on-month diff:

  • POI counts — usually ±0.5% to ±2%. New venues land, closed venues drop, and source-count distributions shift slightly as cross-validation patterns change.
  • Station counts — usually unchanged. A major rail-network change (new line opens, a station rebuilds) shows up sharply when it happens; otherwise it's flat.
  • Transport frequency rollups — can shift when seasonal timetables roll over. Don't be surprised by a step-change in trip counts when a major timetable swap lands.
  • Polygon aggregates — usually unchanged. The Overture upstream cadence is monthly, but the actual content turns over slowly.

If you want stable numbers across a multi-month evaluation, pin to a single snapshot by re-querying anything you're tracking before last_refreshed moves.

ETag

The transport and public-transport endpoints set a weak ETag derived from the country's projection freshness. No endpoint validates If-None-Match, so a conditional request returns a full 200, never a 304.

How to think about SLAs

A few practical guidelines if you're building a product on top of the API:

  • Don't assume real-time freshness. A coffee shop that closed last week may still appear; a new tube line that opened yesterday won't appear until the next rebuild.
  • Don't promise pinpoint stability either. Cross-validation results can shift between rebuilds — a 2-source POI can become 1-source if one upstream feed drops it, which moves any count you compute behind a min_sources filter.
  • Do treat each snapshot as immutable. Within one snapshot, the same request always returns the same response. That's a useful guarantee for caching and for reproducing analytics.
  • Do surface freshness to your end users where it matters. A real-estate dashboard built on this data should note "Data as of April 2026" rather than implying it's live.

Where next