Data Query Endpoint¶
The /data/query endpoint provides the ability to query for available data files by product, one or more sites, a specified date range, and optionally by release, package type, and whether or not the query results should include provisional data. By default, provisional data are excluded from results and the latest available release data are included.
Data Releases¶
The /data/query endpoints allow filtering the response based on data available within a particular release by adding a release query parameter to GET requests or by specifying the release property within the request body object to POST requests. For example:
GET Request¶
/data/query?productCode={productCode}&siteCode={siteCode}&startDateMonth={startDateMonth}&endDateMonth={endDateMonth}&release={releaseTag}
POST Request¶
/data/query
{
"productCode": "DP1.00001.001",
"siteCodes": ["ABBY"],
"startDateMonth": "2023-01",
"endDateMonth": "2023-12",
"release": "RELEASE-2024"
}
The learn more about data releases, see: releases
Paths¶
GET /data/query¶
Description¶
Get files available for a given product, one or more sites, date range, release, package combination
Parameters¶
| Type | Name | Description | Schema |
|---|---|---|---|
| Query | productCode required | Product code to query for files | string |
| Query | siteCode required | One or more four letter site codes to query for files | string |
| Query | startDateMonth required | YYYY-MM start date month to query for files | string |
| Query | endDateMonth required | YYYY-MM end date month to query for files | string |
| Query | release optional | The name of the release to query for | string |
| Query | package optional | Package type to query, basic or expanded | enum (basic, expanded) |
| Query | includeProvisional optional | Optionally include provisional data in the query | boolean |
Responses¶
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Available files | Response 200 |
| 400 | One or more invalid paramaters 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 Query
POST /data/query¶
Description¶
Get files available for a given product, one or more sites, date range, release, package combination
Request Body¶
| Name | Description | Schema |
|---|---|---|
| productCode required | Product code to query for files | string |
| siteCodes required | One or more four letter site codes to query for files | [string] |
| startDateMonth required | YYYY-MM start date month to query for files | string |
| endDateMonth required | YYYY-MM end date month to query for files | string |
| release optional | The name of the release to query for | string |
| package optional | Package type to query, basic or expanded | enum (basic, expanded) |
| includeProvisional optional | Optionally include provisional data in the query | boolean |
Example JSON Request Body
{
"productCode": "DP1.00001.001",
"siteCodes": ["ABBY"],
"startDateMonth": "2023-01",
"endDateMonth": "2023-12",
"release": "RELEASE-2024",
"package": "basic",
"includeProvisional": false
}
Responses¶
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Available files | Response 200 |
| 400 | One or more invalid paramaters 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 Query
Definitions¶
data¶
| Name | Description | Schema |
|---|---|---|
| productCode | Revisioned, shortened code for the data product (DP1.00001.001, DP1.10072.001, etc) | string |
| siteCodes | List of four character site codes available | [string] |
| startDate | The start date of the query interval | string (date-time) |
| endDate | The end date of the query interval | string (date-time) |
| packageType | The type of package, basic or expanded | string |
| releases | The list of available releases for the query | [releases] |
releases¶
Describes a release package
| Name | Description | Schema |
|---|---|---|
| release | The name of the release | string |
| generationDate | The generation date of the release | string (date-time) |
| packages | The list of available packages within the release for the query | [packages] |
packages¶
Describes a data package
| Name | Description | Schema |
|---|---|---|
| domainCode | Three character domain abbreviation (D01, D02, etc) for the domain this package is in | string |
| siteCode | Four character code for the site | string |
| month | The available month, formatted as YYYY-MM | string |
| packageType | The type of package, basic or expanded | string |
| generationDate | The generation date of the package | string (date-time) |
| files | The list of available files within the package for the query | [file] |
file¶
| Name | Description | Schema |
|---|---|---|
| name | Filename | string |
| size | File size in bytes | number (int) |
| md5 | MD5 value in hex | string |
| crc32c | CRC32C value in hex | string |
| url | Download URL | string |
error¶
| Name | Schema |
|---|---|
| detail optional | string |
| status optional | number (int) |