API Reference

This page contains the complete API reference for the NOAA Climate API client.

Client

NOAA Climate Data Online API client.

class noaa.client.NOAA(token)[source]

Bases: object

Client for interfacing with NOAA Climate Data Online API.

Parameters:: token (str) – Access token from NOAA

BASE_URL = 'https://www.ncdc.noaa.gov/cdo-web/api/v2/'

get_data(dataset_id, start_date, end_date, data_type_id=None, location_id=None, station_id=None, units='metric', sort_field=None, sort_order='asc', limit=25, offset=0, include_metadata=False)[source]

Get climate data from CDO.

Parameters:

dataset_id (str) – Dataset identifier (required)
start_date (str) – Start date in ISO format (required)
end_date (str) – End date in ISO format (required)
data_type_id (str | Sequence[str] | None) – Data type identifier(s), defaults to None
location_id (str | Sequence[str] | None) – Location identifier(s), defaults to None
station_id (str | Sequence[str] | None) – Station identifier(s), defaults to None
units (str) – Units (‘metric’ or ‘standard’), defaults to “metric”
sort_field (str | None) – Field to sort by, defaults to None
sort_order (str) – Sort order (‘asc’ or ‘desc’), defaults to “asc”
limit (int) – Maximum results (0-1000), defaults to 25
offset (int) – Result offset, defaults to 0
include_metadata (bool) – Include metadata in response, defaults to False

Returns:

API response data

Return type:

dict

get_data_categories(category_id=None, dataset_id=None, location_id=None, station_id=None, start_date=None, end_date=None, sort_field=None, sort_order='asc', limit=25, offset=0)[source]

Get available data categories or info on a specific category.

Parameters:

category_id (str | None) – Category identifier, defaults to None
dataset_id (str | Sequence[str] | None) – Dataset identifier(s), defaults to None
location_id (str | Sequence[str] | None) – Location identifier(s), defaults to None
station_id (str | Sequence[str] | None) – Station identifier(s), defaults to None
start_date (str | None) – Start date in ISO format, defaults to None
end_date (str | None) – End date in ISO format, defaults to None
sort_field (str | None) – Field to sort by, defaults to None
sort_order (str) – Sort order (‘asc’ or ‘desc’), defaults to “asc”
limit (int) – Maximum results (0-1000), defaults to 25
offset (int) – Result offset, defaults to 0

Returns:

API response data

Return type:

dict

get_data_types(type_id=None, dataset_id=None, location_id=None, station_id=None, data_category_id=None, start_date=None, end_date=None, sort_field=None, sort_order='asc', limit=25, offset=0)[source]

Get available data types or info on a specific type.

Parameters:

type_id (str | None) – Type identifier, defaults to None
dataset_id (str | Sequence[str] | None) – Dataset identifier(s), defaults to None
location_id (str | Sequence[str] | None) – Location identifier(s), defaults to None
station_id (str | Sequence[str] | None) – Station identifier(s), defaults to None
data_category_id (str | Sequence[str] | None) – Data category identifier(s), defaults to None
start_date (str | None) – Start date in ISO format, defaults to None
end_date (str | None) – End date in ISO format, defaults to None
sort_field (str | None) – Field to sort by, defaults to None
sort_order (str) – Sort order (‘asc’ or ‘desc’), defaults to “asc”
limit (int) – Maximum results (0-1000), defaults to 25
offset (int) – Result offset, defaults to 0

Returns:

API response data

Return type:

dict

get_datasets(dataset_id=None, data_type_id=None, location_id=None, station_id=None, start_date=None, end_date=None, sort_field=None, sort_order='asc', limit=25, offset=0)[source]

Get available datasets or info on a specific dataset.

Parameters:

dataset_id (str | None) – Dataset identifier, defaults to None
data_type_id (str | Sequence[str] | None) – Data type identifier(s), defaults to None
location_id (str | Sequence[str] | None) – Location identifier(s), defaults to None
station_id (str | Sequence[str] | None) – Station identifier(s), defaults to None
start_date (str | None) – Start date in ISO format, defaults to None
end_date (str | None) – End date in ISO format, defaults to None
sort_field (str | None) – Field to sort by, defaults to None
sort_order (str) – Sort order (‘asc’ or ‘desc’), defaults to “asc”
limit (int) – Maximum results (0-1000), defaults to 25
offset (int) – Result offset, defaults to 0

Returns:

API response data

Return type:

dict

get_location_categories(location_category_id=None, dataset_id=None, start_date=None, end_date=None, sort_field=None, sort_order='asc', limit=25, offset=0)[source]

Get available location categories or info on a specific category.

Parameters:

location_category_id (str | None) – Location category identifier, defaults to None
dataset_id (str | Sequence[str] | None) – Dataset identifier(s), defaults to None
start_date (str | None) – Start date in ISO format, defaults to None
end_date (str | None) – End date in ISO format, defaults to None
sort_field (str | None) – Field to sort by, defaults to None
sort_order (str) – Sort order (‘asc’ or ‘desc’), defaults to “asc”
limit (int) – Maximum results (0-1000), defaults to 25
offset (int) – Result offset, defaults to 0

Returns:

API response data

Return type:

dict

get_locations(location_id=None, dataset_id=None, location_category_id=None, data_category_id=None, start_date=None, end_date=None, sort_field=None, sort_order='asc', limit=25, offset=0)[source]

Get available locations or info on a specific location.

Parameters:

location_id (str | None) – Location identifier, defaults to None
dataset_id (str | Sequence[str] | None) – Dataset identifier(s), defaults to None
location_category_id (str | Sequence[str] | None) – Location category identifier(s), defaults to None
data_category_id (str | Sequence[str] | None) – Data category identifier(s), defaults to None
start_date (str | None) – Start date in ISO format, defaults to None
end_date (str | None) – End date in ISO format, defaults to None
sort_field (str | None) – Field to sort by, defaults to None
sort_order (str) – Sort order (‘asc’ or ‘desc’), defaults to “asc”
limit (int) – Maximum results (0-1000), defaults to 25
offset (int) – Result offset, defaults to 0

Returns:

API response data

Return type:

dict

get_stations(station_id=None, dataset_id=None, location_id=None, data_category_id=None, data_type_id=None, extent=None, start_date=None, end_date=None, sort_field=None, sort_order='asc', limit=25, offset=0)[source]

Get available stations or info on a specific station.

Parameters:

station_id (str | None) – Station identifier, defaults to None
dataset_id (str | Sequence[str] | None) – Dataset identifier(s), defaults to None
location_id (str | Sequence[str] | None) – Location identifier(s), defaults to None
data_category_id (str | Sequence[str] | None) – Data category identifier(s), defaults to None
data_type_id (str | Sequence[str] | None) – Data type identifier(s), defaults to None
extent (str | None) – Geographic extent for search, defaults to None
start_date (str | None) – Start date in ISO format, defaults to None
end_date (str | None) – End date in ISO format, defaults to None
sort_field (str | None) – Field to sort by, defaults to None
sort_order (str) – Sort order (‘asc’ or ‘desc’), defaults to “asc”
limit (int) – Maximum results (0-1000), defaults to 25
offset (int) – Result offset, defaults to 0

Returns:

API response data

Return type:

dict

Exceptions

Custom exceptions for the NOAA API client.

exception noaa.exceptions.APIError[source]

Bases: NOAAException

Raised when the API returns an error.

exception noaa.exceptions.NOAAException[source]

Bases: Exception

Base exception for NOAA API errors.

exception noaa.exceptions.ValidationError[source]

Bases: NOAAException

Raised when input validation fails.

Validators

Input validation functions for the NOAA API client.

noaa.validators.validate_boolean(value, name)[source]

Validate that a value is a boolean.

Parameters:

value (Any)
name (str)

Return type:

None

noaa.validators.validate_limit(limit)[source]

Validate the limit parameter.

Parameters:: limit (int)
Return type:: None

noaa.validators.validate_offset(offset)[source]

Validate the offset parameter.

Parameters:: offset (int)
Return type:: None

noaa.validators.validate_sort_field(sort_field)[source]

Validate the sort_field parameter.

Parameters:: sort_field (str | None)
Return type:: None

noaa.validators.validate_sort_order(sort_order)[source]

Validate the sort_order parameter.

Parameters:: sort_order (str)
Return type:: None

noaa.validators.validate_string_or_none(value, name)[source]

Validate that a value is a string or None.

Parameters:

value (Any)
name (str)

Return type:

None

noaa.validators.validate_string_or_sequence(value, name)[source]

Validate that a value is a string, sequence of strings, or None.

Parameters:

value (Any)
name (str)

Return type:

None

noaa.validators.validate_units(units)[source]

Validate the units parameter.

Parameters:: units (str)
Return type:: None

Utilities

Utility functions for the NOAA API client.

noaa.utils.build_query_params(params)[source]

Build URL query parameters from a dictionary.

Parameters:: params (Dict[str, Any]) – Dictionary of parameter names and values
Returns:: URL-encoded query string
Return type:: str

noaa.utils.join_ids(value)[source]

Join a sequence of IDs into an ampersand-separated string.

Parameters:: value (str | Sequence[str] | None) – Single ID or sequence of IDs
Returns:: Joined string or original value
Return type:: str | None

noaa.utils.make_api_request(url, headers)[source]

Make a GET request to the API.

Parameters:

url (str) – Full URL including query parameters
headers (Dict[str, str]) – Request headers

Returns:

Parsed JSON response

Return type:

dict

noaa.utils.parse_date(date_value, name, include_time=False)[source]

Parse and format a date value for the API.

Parameters:

date_value (str | datetime | None) – Date as string or datetime object
name (str) – Name of the parameter (for error messages)
include_time (bool) – Whether to include time component

Returns:

Formatted date string or None

Return type:

str | None