canonical: https://jentic.com/apis/noaa.gov/noaa

# Noaa Gov NOAA Climate Data Online (CDO) API

NOAA Climate Data Online (CDO) v2 exposes the National Centers for Environmental Information's archive of climate datasets, data categories, data types, locations, stations, and observed values. Agents can list and filter datasets like GHCND and GSOM, drill into the data types and categories each dataset publishes, look up monitoring stations and location codes, and pull observed values across date ranges and station sets via /data. The service is rate limited to 5 requests per second and 10,000 per day per token, and authentication is handled by an apiKey passed in the token header.

## For AI agents

Query NOAA's climate dataset catalog and pull observed weather and climate values by station, location, and date range across 13 CDO v2 endpoints.

## Scope

Does not handle real-time forecasts, severe weather alerts, or marine and aviation products - use for NOAA Climate Data Online historical observations only.

## Capabilities

- List available climate datasets and inspect their metadata via /datasets and /datasets/{id}
- Discover data categories and data types tied to a dataset through /datacategories and /datatypes
- Look up monitoring stations and filter by dataset, location, or geographic extent via /stations
- Resolve location codes for cities, counties, states, and zip codes through /locations and /locationcategories
- Pull observed values for selected stations and date ranges from /data with units and limit controls
- Filter dataset coverage by date range and data type to narrow large result sets before /data calls

## Use cases

### Climate Trend Analysis

Researchers and ESG teams need consistent historical climate observations to compute trends across decades. The CDO API exposes datasets like GHCND and GSOM with /data endpoints that accept stationid, datatypeid, startdate, and enddate parameters, returning structured observation rows. By chaining /stations, /datatypes, and /data calls an agent can build a reproducible pipeline for temperature, precipitation, and snow trend analysis without scraping NCEI bulk archives.

Example prompt: Call /stations with locationid for a US state, then /data with datasetid=GHCND, the chosen stationid, datatypeid=TAVG, startdate=2014-01-01, enddate=2024-01-01

### Insurance Risk Geolocation

Climate-aware underwriting workflows need historical observations tied to specific zip codes or counties. The /locations and /locationcategories endpoints resolve zip and FIPS codes to NOAA location ids, which can then be passed to /stations and /data. This produces a structured chain from a policy address to nearby station observations and historical extreme values for a risk score.

Example prompt: Resolve a US zip to a NOAA locationid via /locations?locationcategoryid=ZIP, list /stations for that location, and pull /data for the GSOM dataset over the last 30 years

### Operational Weather Reporting

Operations and logistics teams need a daily report of station-level conditions across a fixed set of monitored sites. The /data endpoint accepts a list of stationids and a date range, returning observed values for each datatype requested. With /datasets and /datatypes the report can adapt automatically when NOAA adds or deprecates a data type without breaking the pipeline.

Example prompt: Call /data with datasetid=GHCND, a comma-separated list of stationids, datatypeid=PRCP, and yesterday's date as both startdate and enddate

### AI Agent Climate Lookup

An LLM-powered agent answering questions like 'what was the average rainfall in San Francisco last summer?' can use Jentic to find and call the right CDO endpoint without hand-coding location and station resolution. Jentic search routes the question to /data with the correct dataset, datatype, and date range derived from intent, while the NOAA token stays in the vault.

Example prompt: Use Jentic to chain /locations, /stations, and /data to answer 'average daily precipitation for San Francisco in summer 2024'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /datasets | List available NOAA CDO datasets |
| GET | /datasets/{id} | Get metadata for a specific dataset |
| GET | /datatypes | List data types reported across datasets |
| GET | /locations | List location codes filtered by category |
| GET | /stations | List monitoring stations filtered by dataset or location |
| GET | /data | Retrieve observed values for a dataset, station, datatype, and date range |
| GET | /datacategories | List data categories grouping data types |

## Key resources

- **Datasets** — Catalog of NOAA CDO datasets such as GHCND, GSOM, and NORMAL_DLY
- **Data Categories** — Group data types into categories like temperature, precipitation, and wind
- **Data Types** — Specific observed measurements with units and dataset coverage
- **Locations** — Geographic codes for cities, counties, states, zip codes, and climate regions
- **Stations** — Individual monitoring stations with metadata and reporting coverage
- **Data** — Observed values returned for a dataset, station, datatype, and date range

## Why Jentic

- **Setup:** Wiring NOAA Climate Data Online by hand means adding its token header, building requests against its CDO host (https://www.ncei.noaa.gov/cdo-web/api/v2), and handling its paging yourself. Through Jentic you install once, import the CDO API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** CDO is a read-only historical observations API, so scope by operation: limit the agent to the calls it needs, such as listing stations or fetching data, and leave out data categories or datatype lookups unless you add them. You choose the operations it may call.
- **Credential handling:** Your CDO token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find weather stations for a location' or 'fetch historical climate data', and Jentic returns the matching CDO operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **OpenWeather API** — OpenWeather provides current and forecast weather globally rather than NOAA's deep US historical archive.
- **Weatherbit API** — Weatherbit exposes historical and forecast weather data with global coverage and a single token model.
- **NASA APIs** — NASA APIs expose Earth-observation imagery and atmospheric datasets that complement NOAA's surface climate observations.

## FAQ

### What authentication does the NOAA CDO API use?

NOAA CDO uses an apiKey passed as the token header. Request a free token from the NOAA CDO portal. Through Jentic the token is stored in the vault and injected on every call without exposing it to the agent.

### Can I get historical daily temperature data with the NOAA CDO API?

Yes. Call /data with datasetid=GHCND, the stationid for the location, datatypeid=TAVG (or TMIN/TMAX), and your startdate and enddate. The response returns daily observed values with units.

### What are the rate limits for the NOAA CDO API?

NOAA enforces 5 requests per second and 10,000 requests per day per token, as declared in the spec's tokenAuth description. Jentic handles 429 responses with backoff and surfaces a clear error if the daily quota is exhausted.

### How do I find weather stations near a specific zip code through Jentic?

Run pip install jentic, search Jentic for 'find noaa stations near a zip code', then chain /locations?locationcategoryid=ZIP to resolve the zip to a NOAA locationid and /stations?locationid=... to list nearby stations. Jentic injects the token automatically.

### Is the NOAA CDO API free to use?

Yes. Tokens are issued free of charge from the NOAA CDO portal. Usage is bound by the 5 req/sec and 10,000 req/day quotas per token.

### Which datasets are available through the NOAA CDO API?

Call /datasets to list the full catalog, including daily summaries (GHCND), monthly summaries (GSOM), normals (NORMAL_DLY, NORMAL_MLY), and other long-running NCEI products. /datasets/{id} returns coverage metadata.

### Can I limit what my agent is allowed to do with the NOAA CDO API?

Yes. Because you run Jentic One yourself, your own rules decide which CDO operations the agent may call and which token it uses. Since CDO is read-only, you can scope by operation, allowing just the calls the agent needs, such as listing stations via /stations or fetching observations via /data, while leaving out /datacategories and /datatypes lookups. The NOAA token stays with your instance and is injected only for the operations you permit.