The NCEI Access Data Service queries use HTTP 1.1 GET request and the endpoint is located off the base URL at .../access-data-service/api/v1/data.
Request Endpoint Parameters
The NCEI Access Data Service endpoint allows several parameters to select and retrieve data from available datasets. The request parameters are passed using a GET request. Some of these request parameters change based on the dataset parameter that is passed.
Datasets — dataset
The dataset parameter selects the dataset to query for data. Please note that all the datasets are NOT available through the NCEI Access Data Service API, however new datasets are added quarterly.
Station Identifiers — stations
The stations parameter adds a comma separated list of station identifiers for selection and subsetting.
Start Date — startDate
This is the date to select from the dataset for a given start date. 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 plus symbol (+) must be URL encoded at “%2B” or it will not validate. 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 example:
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:
End Date — endDate
This is the date to select datasets whose period of record (PoR) starts on or after the given endDate. 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 plus symbol (+) must be URL encoded as “%2B” or it will not validate. If the start date is required for the dataset then you must include the startDate parameter.
Data Types, Observations/Variables — dataTypes
Data Types allows the selection of one or many dataTypes. Datasets have different names for the data types (e.g., variables, observations). The dataTypes parameter is used with a comma-separated list. This parameter is case-sensitive and will respond with an HTTPS Status Code: 400 Bad Request and JSON with more information.
Bounding Box (N,W,S,E) — boundingBox
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).
Data Format — format
The format parameter allows the user to select how the data should be formatted. Note that some data formats ignore certain data types. For example, PDF data may only display data types for a report, and not for the requested dataTypes.
These are the available formats:
csv — Comma-Separated Values (CSV)
ssv — Space-Separated Values (SSV)
pdf — Portable Document Format (PDF)
netcdf — Network Common Data Form (NetCDF)
Result Options — options
The API supports an options parameter that turns features on and off. Options are separated by commas and the respective values are separated by a colon (:); boolean values are represented by true or false,or zero (0) and one (1). Options can either pass as a comma-separated list:
or individually as URL parameters:
Display Data Attributes — includeAttributes
Includes the attribute for a selected datatype. These are typically comma separated (e.g., “T,,0,0700”), and added to the results if the includeAttributes parameter is set to true. This value can be the word true or a numeric representation of the boolean value, 1. The default value is false or 0 and will not display datatype(s) attributes.
Include Station Name — includeStationName
Includes the station’s name, if available, for the selected dataset and data type. This value can be the word true or a numeric representation of the boolean value, 1. The default value is false or 0 and will not display datatype(s) attributes.
Display Station Location — includeStationLocation
Includes the station’s location, if available, for the selected dataset and data type. This value can be the word true or a numeric representation of the boolean value, 1. The default value is false or 0 and will not display datatype(s) attributes.
Converting Units — units
The units parameter converts the output data for datasets and datatypes that support conversion to either “metric” or “standard” units.
The NCEI Access Search Service returns appropriate 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.