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 |
| 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 |
| 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) |