UK Data AtlasAPI

Using the API

Caching

Data only changes when a new Atlas release is published, so most requests can be answered from a cache. The API gives you everything you need to avoid downloading the same thing twice.

What the API sends

  • ETag: a fingerprint of the exact bytes in the response.
  • Cache-Control: public, max-age=300, must-revalidate, so a cache can reuse a response for five minutes, then check it's still current.
  • Errors are sent with Cache-Control: no-store, so a temporary problem is never cached.

Conditional requests

Send a response's ETag back in an If-None-Match header. If nothing has changed, you get 304 Not Modified with an empty body, which is quick and costs almost nothing:

# The first request returns an ETag header
curl -i "https://api.ukdataatlas.com/v1/measures/population"

# Send it back; an unchanged resource answers 304 with no body
curl -i "https://api.ukdataatlas.com/v1/measures/population" \
  -H 'If-None-Match: "<etag from the first response>"'

Browsers and most HTTP caches do this for you automatically.

Checking current resources

Map resources are part of the current Atlas release. Store the release id with your import and use its ETag when checking whether a current resource has changed.