Skip to content

Data Endpoint

The /data endpoint shows which monthly data files are available, and provides URLs to downloadable files. Several terabytes of data are presently available. To keep data files to a reasonable size, they are generally arranged in product/site/monthly chunks. Even so, files can be large and you may find it worthwhile to check the size attribute before downloading. Also note that some provided URLs are from a Google Cloud Storage service and expire 1 hour after generation. If the time between when you obtain a URL and start downloading the file is more than 1 hour, you may need to obtain a new URL before proceeding.

Data Releases

The /data endpoints allow filtering the response based on data available within a particular release by adding a releasequery parameter to requests. For example:

/data/{productCode}/{siteCode}/{year-month}?release={releaseTag}

The learn more about data releases, see: releases

Paths

GET /data/{productCode}/{siteCode}/{year-month}

Description

Get files available for a given product/site/month combination

Parameters

Type Name Description Schema
Path productCode
required
Product to check for files string
Path siteCode
required
Site to check for files string
Path year-month
required
YYYY-MM month to check for files string
Query package
optional
Package type to return, basic or expanded enum (basic, expanded)
Query release
optional
The name or tag of the release to get availability for. string

Responses

HTTP Code Description Schema
200 Available files Response 200
400 Product, site not found or invalid date range specified Response 400
default General error error
Response 200
Name Schema
data data
Response 400
Name Schema
errors
optional
[error]

Produces

  • application/json

Tags

  • Data

GET /data/{productCode}/{siteCode}/{year-month}/{filename}

Description

Get a file for a given product/site/month/filename combination

Parameters

Type Name Description Schema
Path filename
required
The name of the file string
Path productCode
required
Product to check for files string
Path siteCode
required
Site to check for files string
Path year-month
required
YYYY-MM month to check for files string
Query package
optional
Package type to return, basic or expanded enum (basic, expanded)
Query release
optional
The name of the release to get for string

Responses

HTTP Code Description Schema
200 Available file data string (binary)
302 Found available file and redirects to data string (binary)
400 Invalid file name specified Response 400
default General error error

Response 400

Name Schema
errors
optional
[error]

Produces

  • application/octet-stream

Tags

  • Data

GET /data/package/{productCode}/{siteCode}/{year-month}

Description

Get a data package for a given product/site/month and package combination

Parameters

Type Name Description Schema
Path productCode
required
Product to check for files string
Path siteCode
required
Site to check for files string
Path year-month
required
YYYY-MM month to check for files string
Query package
optional
Package type to return, basic or expanded enum (basic, expanded)
Query release
optional
The name of the release to get for string

Responses

HTTP Code Description Schema
200 Available data package as a ZIP The ZIP package
400 Invalid product, site, or month specified Response 400
default General error error

Response 400

Name Schema
errors
optional
[error]

Produces

  • application/zip

Tags

  • Data

Definitions

data

Name Description Schema
productCode The product code. string
siteCode The four letter site code. string
month The available month. Formatted as YYYY-MM. string
release The name of the associated release. string
packages
optional
The set of data packages. [packages]
files The set of data files. [file]
externalData
optional
The set of externally hosted data. [externalData]

packages

Name Description Schema
type The type of package. string
url The URL to the data package API endpoint. string

file

Info

Note that the crc32 checksum property is deprecated in favor of the crc32c checksum property.

Name Description Schema
name Filename string
size File size in bytes number (int)
md5 MD5 value in hex string
crc32 DEPRECATED.
CRC32 value in hex
string
crc32c CRC32C value in hex string
url Download URL string

externalData

Name Description Schema
name The name of the external data object string
type The type of external data link provided. string
url URL to external data. number (int)

error

Name Schema
detail
optional
string
status
optional
number (int)