Querying the NOAA NCEI Database¶

Authors¶

Deborah Khider , Dhiren Oswal

Preamble¶

In the previous chapter, you learned how to create a NOAADataset object and its many functionalities. This tutorial demonstrates how to query the database.

Goals¶

Perform query on NOAA NCEI using their search parameters.

Prerequisite¶

Understanding of NOAA datasets and associated search API
PyleoTUPS NOAADataset object

Reading time¶

15 min

Let’s import our packages!

import pyleotups as pt
import pandas as pd

Geographical Query¶

Let’s start with a simple geographical query. Let’s look for all the datasets within 5°S-5°N and 109-125°E, roughly corresponding to the Indo-Pacific Warm Pool.

Let’s create another Dataset object to store this new search:

ds = pt.NOAADataset()

Querying terms and their definitions are available through NOAA: https://www.ncei.noaa.gov/access/paleo-search/api

res = ds.search_studies(max_lat=5, min_lat=-5, max_lon=109,
                       min_lon=125)

[2026-04-06 14:39:05,912][INFO] - search_studies: Limit defaulted to 100 (PyleoTUPS).
[2026-04-06 14:39:05,913][INFO] - search_studies: Input Query includes geographical bounds. Inspect the results to ensure they match your intended region as one study can contain sites across various parts of the world.

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=100&minLat=-5&maxLat=5&minLon=125&maxLon=109

Parsing NOAA studies: 100%|██████████| 100/100 [00:00<00:00, 7126.14it/s]
[2026-04-06 14:39:07,565][INFO] - Retrieved 100 studies.

Warning: One of the default parameters in `search_studies` is how many studies can be returned by query. The default is 100.

We got 100 datasets, which means we may have hit the limit. Let’s increase to 500 and see what happens:

res = ds.search_studies(max_lat=5, min_lat=-5, max_lon=109,
                       min_lon=125, limit=500)

[2026-04-06 14:39:20,174][INFO] - search_studies: Limit set to 500.
[2026-04-06 14:39:20,175][INFO] - search_studies: Input Query includes geographical bounds. Inspect the results to ensure they match your intended region as one study can contain sites across various parts of the world.

Request URL: https://www.ncei.noaa.gov/access/paleo-search/study/search.json?dataPublisher=NOAA&limit=500&minLat=-5&maxLat=5&minLon=125&maxLon=109

Parsing NOAA studies: 100%|██████████| 387/387 [00:00<00:00, 3888.23it/s]
[2026-04-06 14:39:23,270][INFO] - Retrieved 387 studies.

We have 387 studies now, far from the maximum of 500 so it seams we collected all records.

You can use the same functions as described above the retrieve information. For instance, let’s have a look at the data tables: