Dataset Search Endpoint
Dataset searches use the v1/datasets endpoint to locate datasets available through the NCEI Common Access Search Service.
Dataset Search Request Endpoint Parameters
The NCEI Common Access Search Service dataset search endpoint allows several parameters to select and retrieve datasets based on the requested search terms passed to the service. The request parameters are passed using a GET request.
Dataset Temporal Range — startDate/endDate
This is the date to select datasets whose period of record (PoR) starts on or after the given startDate. This parameter is an ISO 8601 date (YYYY-MM-DD) -or- ISO 8601 combined date and time format (YYYY-MM-DDTHH:mm:ss). If using an ISO 8601 combined date and time format, the T that separates the time is NOT optional. The ISO 8601 combined date and time also supports optional time zone representations. Use Z or z for UTC and +HH:mm or -HH:mm for the offset from UTC. The start and end dates are not required. The startDate must come before the endDate parameter. Some datasets are averages over time and may ignore parts of a date.
ISO 8601 date format examples:
ISO 8601 combined date and time examples:
For UTC hour and minute offsets (HH:mm), the plus symbol (+) must be URL encoded as “%2B” or it will not validate:
Bounding Box (N,W,S,E) — bbox
The bounding box is used to select data from a geographic location contained within the coordinates, given as four comma separated numbers. North and South range from -90 to 90 and East and West range from -180 to 180. If these are not set the geographic extent defaults to the entire globe (90,-180,-90,180).
Keywords — keywords
A comma separated list of Global Change Master Directory (GCMD) Keywords or other terms that can be used to locate datasets. The keywords that are available come from the ISO 19115-2 metadata records. A full list is available from the service in an empty query in the keywords.bucket array. The complete list of GCMD keywords are available as an XML document here. Here is an example of the keyword parameter.
Text — text
The text parameter used to locate datasets by matching the terms of the dataset name and description.
Available — available
A boolean (true or false) used to locate datasets based on whether they are available in the Data Search Endpoint.
Dataset Search Example Request
Below are request examples to the NCEI Common Access Search Service.
Search Request Responses
The NCEI Common Access Search Service returns HTTP/1.1 status codes and response headers depending on the request and service status. These responses follow RFC 2616 (Fielding, et al).
400 - Bad Request
The request is malformed and needs to be modified in order to execute. The response headers contain the correct HTTP/1.1 400 Bad Request and provide a JSON response.
500 - Internal Server Error
The 500 response code is returned when there is an issue with the service.