The National Centers for Environmental Information (NCEI) Access Data Service
provides a RESTful application programming interface (API) to access and subset data based on the
set of
parameters to the v1 URL. Depending on the dataset the API can format the data
as comma-separated values (
CSV specification
), space-separated values (SSV), JavaScript Object Notation (
JSON specification
), Portable Document Format (
PDF standard documentation
) and Network Common Data Form (
NetCDF documentation
). The NCEI Access Data Service is only available via HTTP Strict Transport Security (
HSTS specification
) following
Federal government HTTPS policy
.
Request Endpoint
The NCEI Access Data Service queries use HTTP 1.1
GET method specification
request and the endpoint is located off the base URL at .../access/services/data/v1.
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.
...?dataset=daily-summaries
Station Identifiers — stations
The stations parameter adds a comma separated list of station identifiers for
selection and subsetting.
...&stations=USC00457180,USC00390043
Start Date — startDate
This is the date to select from the dataset for a given start date. This parameter is an
ISO 8601 date and time format standard
date (YYYY-MM-DD) -or- ISO 8601 combined date and time format (YYYY-MM-DDTHH:mm:ss).
If using an
ISO 8601 date and time format standard
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. 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.
For UTC hour and minute offsets (HH:mm), the plus symbol (+) must be URL encoded as "%2B" or it will
not validate:
...&startDate=2009-01-27T08:45:00%2B04:00
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.
...&endDate=1945-07-12
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.
...&dataTypes=MLY-PRCP-NORMAL,MLY-TMIN-NORMAL
Bounding Box (N,W,S,E) — bbox
The bounding box (bbox) 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).
...&bbox=49.795,-2.073,49.183,-0.992
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)
json — JavaScript Object Notation (JSON)
pdf — Portable Document Format (PDF)
netcdf — Network Common Data Form (NetCDF)
...&format=json
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:
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.
...&includeAttributes=true
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.
...&includeStationName=true
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.
...&includeStationLocation=1
Converting Units — units
The units parameter converts the output data for datasets and datatypes that support
conversion to either "metric" or "standard" units.
...&units=metric
Access Data Service Example API Requests
Below are full URL examples of API requests to the NCEI Common Access Data Service using different format types.
The URLs include the request endpoint and any request endpoint parameters that are being passed to the service.
A successful response will result in a download of the requested file.
Example Request URL for the default CSV file type:
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
HTTP/1.1 specification 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.
{
errorMessage: "Bad Request",
errorCode: 400,
errors: [
{
field: "units",
message: "Invalid units. Valid units are standard or metric.",
value: "0xFE00BA1A00000000"
}
]
}
500 - Internal Server Error
The 500 response code is returned when there is an issue with the service.
{
errorMessage: "An unexpected error occurred while servicing your request.",
errorCode: 500
}
An official website of the United States government
