USGS dataretrieval Python Package `get_field_measurements()` Examples

This notebook provides examples of using the Python dataretrieval package to retrieve surface water field measurement data for a United States Geological Survey (USGS) monitoring location. The dataretrieval package provides a collection of functions to get data from the USGS Water Data API and other online sources of hydrology and water quality data.

Install the Package

Use the following code to install the package if it doesn’t exist already within your Jupyter Python environment.

[1]:

!pip install dataretrieval

Requirement already satisfied: dataretrieval in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (0.1.dev1+g7f64c2de7)
Requirement already satisfied: httpx in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from dataretrieval) (0.28.1)
Requirement already satisfied: pandas<4.0.0,>=2.0.0 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from dataretrieval) (3.0.3)
Requirement already satisfied: numpy>=1.26.0 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (2.4.6)
Requirement already satisfied: python-dateutil>=2.8.2 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from pandas<4.0.0,>=2.0.0->dataretrieval) (2.9.0.post0)
Requirement already satisfied: six>=1.5 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from python-dateutil>=2.8.2->pandas<4.0.0,>=2.0.0->dataretrieval) (1.17.0)
Requirement already satisfied: anyio in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (4.13.0)
Requirement already satisfied: certifi in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (2026.5.20)
Requirement already satisfied: httpcore==1.* in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (1.0.9)
Requirement already satisfied: idna in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpx->dataretrieval) (3.16)
Requirement already satisfied: h11>=0.16 in /opt/hostedtoolcache/Python/3.13.13/x64/lib/python3.13/site-packages (from httpcore==1.*->httpx->dataretrieval) (0.16.0)

Load the package so you can use it along with other packages used in this notebook.

[2]:

from IPython.display import display

import dataretrieval.waterdata as waterdata

Basic Usage

The dataretrieval package has several functions that allow you to retrieve data from the USGS Water Data API. This example uses the get_field_measurements() function to retrieve surface water field measurements for a USGS monitoring location. Field measurements are physically measured values (such as gage height and discharge) collected during a visit to a monitoring location, and are primarily used as calibration readings for the automated sensors collecting continuous data. The function accepts the following arguments (all optional):

monitoring_location_id (string or list of strings): A unique identifier representing a single monitoring location, formed by combining the responsible agency code with the location ID number, separated by a hyphen (e.g. USGS-10109000). A list may be supplied to query multiple locations.
parameter_code (string or list of strings): One or more 5-digit parameter codes identifying the constituent measured and its units of measure.
time (string): The date an observation represents. Accepts an RFC 3339 date-time, a bounded or half-bounded interval (e.g. 2019-01-01/2019-12-31 or 2019-01-01/..), or an ISO 8601 duration (e.g. P20Y for the past 20 years).
skip_geometry (boolean): If True, response geometries are omitted and a plain (non-spatial) data frame is returned.

Additional query parameters such as approval_status, qualifier, bbox, and limit are also supported; see the get_field_measurements() docstring for the full list.

Example 1: Get all of the field measurements for a single monitoring location

[3]:

measurements1 = waterdata.get_field_measurements(monitoring_location_id="USGS-10109000")
print("Retrieved " + str(len(measurements1[0])) + " data values.")

Retrieving: field-measurements · 1 page · 1,916 rows
No API key detected — register for higher rate limits at https://api.waterdata.usgs.gov/signup/

Retrieved 1916 data values.

Interpreting the Result

The get_field_measurements() function returns a tuple of two objects: a pandas data frame and an associated metadata object. The data frame is flat, uses a default integer index, and contains a time column holding the date of each measurement (along with columns such as monitoring_location_id, parameter_code, value, and unit_of_measure).

Once you’ve got the data frame, there are several useful things you can do to explore the data.

Display the data frame as a table

[4]:

display(measurements1[0])

	geometry	field_measurements_series_id	field_visit_id	parameter_code	monitoring_location_id	observing_procedure_code	observing_procedure	value	unit_of_measure	time	qualifier	vertical_datum	approval_status	measuring_agency	last_modified	control_condition	measurement_rated	field_measurement_id
0	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	4cd21ba9-8644-ebfc-e053-0100007fd6db	00060	USGS-10109000	Z	Unspecified	17.00	ft^3/s	1951-09-06 16:40:00+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Excellent	63c35558-0c81-48b7-88c1-d161740da572
1	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	4cd21ba9-8644-ebfc-e053-0100007fd6db	00065	USGS-10109000	Z	None	0.94	ft	1951-09-06 16:40:00+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Excellent	882ca3fe-55cf-4415-9fb6-29e2cbf610de
2	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	4cd21977-d55d-efa9-e053-0100007fcc60	00060	USGS-10109000	Z	Unspecified	12.50	ft^3/s	1951-12-13 19:10:00+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Unspecified	a04972f0-e812-4f75-ae22-4759f93a7889
3	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	4cd21977-d55d-efa9-e053-0100007fcc60	00065	USGS-10109000	Z	None	0.88	ft	1951-12-13 19:10:00+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Unspecified	bb14b3f8-c0c3-4a76-ae1b-04db24518d99
4	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	4cd21ba9-8645-ebfc-e053-0100007fd6db	00065	USGS-10109000	Z	None	1.80	ft	1952-04-23 17:25:00+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	32688292-a8aa-4094-a8b9-f3d030e1e1cd
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
1911	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	557f1a12-a17e-46b7-a528-6b606b4d0dd7	00060	USGS-10109000	Z	Acoustic Doppler Current Profiler	143.00	ft^3/s	2026-03-04 22:20:41+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	d7f10aaa-5257-4e15-8441-066afbc8b2e8
1912	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	98c59f70-ce2c-4a4d-9acf-18a179a96c78	00060	USGS-10109000	Z	Acoustic Doppler Current Profiler	245.00	ft^3/s	2026-04-20 16:31:59+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	aa6e5b37-7d5b-4f04-a842-5e43af9eaff4
1913	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	98c59f70-ce2c-4a4d-9acf-18a179a96c78	00065	USGS-10109000	Z	None	3.11	ft	2026-04-20 16:31:59+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	e266883f-7e00-424f-bb3d-0d853d83af62
1914	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	6e48b7b6-152b-4a98-a974-87adf3d0ddc8	00060	USGS-10109000	Z	Acoustic Doppler Current Profiler	354.00	ft^3/s	2026-05-12 20:07:07+00:00	None	None	Provisional	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	42664644-54e6-47f6-819d-ab87128698b1
1915	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	6e48b7b6-152b-4a98-a974-87adf3d0ddc8	00065	USGS-10109000	Z	None	3.38	ft	2026-05-12 20:07:07+00:00	None	None	Provisional	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	e950a43f-92bd-4f48-a43d-85d9d05e634e

1916 rows × 18 columns

Show the data types of the columns in the resulting data frame.

[5]:

print(measurements1[0].dtypes)

geometry                                   geometry
field_measurements_series_id                    str
field_visit_id                                  str
parameter_code                                  str
monitoring_location_id                          str
observing_procedure_code                        str
observing_procedure                             str
value                                       float64
unit_of_measure                                 str
time                            datetime64[us, UTC]
qualifier                                    object
vertical_datum                                  str
approval_status                                 str
measuring_agency                                str
last_modified                   datetime64[us, UTC]
control_condition                               str
measurement_rated                               str
field_measurement_id                            str
dtype: object

The other part of the result returned from the get_field_measurements() function is a metadata object that contains information about the query that was executed to return the data. For example, you can access the URL that was assembled to retrieve the requested data from the USGS Water Data API.

[6]:

print("The query URL used to retrieve the data from the Water Data API was: " + measurements1[1].url)

The query URL used to retrieve the data from the Water Data API was: https://api.waterdata.usgs.gov/ogcapi/v0/collections/field-measurements/items?monitoring_location_id=USGS-10109000&skipGeometry=false&limit=50000

Additional Examples

Example 2: Get all of the field measurements between a start and end date

[7]:

measurements2 = waterdata.get_field_measurements(
    monitoring_location_id="USGS-10109000", time="2019-01-01/2019-12-31"
)
print("Retrieved " + str(len(measurements2[0])) + " data values.")
display(measurements2[0])

Retrieving: field-measurements · 1 page · 18 rows

Retrieved 18 data values.

	geometry	field_measurements_series_id	field_visit_id	parameter_code	monitoring_location_id	observing_procedure_code	observing_procedure	value	unit_of_measure	time	qualifier	vertical_datum	approval_status	measuring_agency	last_modified	control_condition	measurement_rated	field_measurement_id
0	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	80a47f55-5d75-9c33-e053-0100007fa04d	00060	USGS-10109000	Z	Mid-section	83.80	ft^3/s	2019-01-29 19:57:30+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	14b391af-d813-472d-bcc9-d863f33023b0
1	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	80a47f55-5d75-9c33-e053-0100007fa04d	00065	USGS-10109000	Z	None	2.43	ft	2019-01-29 19:57:30+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	625a39f8-dee1-4c44-8b7e-8f9100dae45a
2	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	83ebd5c5-373c-5a52-e053-0100007f5e38	00065	USGS-10109000	Z	None	2.46	ft	2019-03-11 19:29:30+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	1e93c787-ee30-40df-9910-bc83610da5f1
3	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	83ebd5c5-373c-5a52-e053-0100007f5e38	00060	USGS-10109000	Z	Mid-section	94.20	ft^3/s	2019-03-11 19:29:30+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	52f09cdf-5839-470a-a501-f4ba0d6a6ab4
4	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	873f3a85-f698-41b8-e053-0100007fc351	00060	USGS-10109000	Z	Acoustic Doppler Current Profiler	337.00	ft^3/s	2019-04-23 21:39:16+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	23dc6ac6-3268-4581-8a50-caf7527717cf
5	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	873f3a85-f698-41b8-e053-0100007fc351	00065	USGS-10109000	Z	None	3.29	ft	2019-04-23 21:39:16+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	fb29b62b-e442-46e4-ad74-da42b13eaa19
6	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	8b3913bf-9253-4f4f-e053-0100007f3ec4	00060	USGS-10109000	Z	Mid-section	709.00	ft^3/s	2019-06-12 14:02:56+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	1d3af755-8ac3-4413-acae-68ea946fb39d
7	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	8b3913bf-9253-4f4f-e053-0100007f3ec4	00065	USGS-10109000	Z	None	4.09	ft	2019-06-12 14:02:56+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	447b8a00-70c0-47ce-8aba-eb281958407b
8	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	8ef1af85-190d-3d4c-e053-0100007f711a	00065	USGS-10109000	Z	None	2.84	ft	2019-07-30 17:57:17+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Vegetation - Light	Good	2e68cb42-dd72-4f21-8a6b-77d329b687b9
9	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	8ef1af85-190d-3d4c-e053-0100007f711a	00060	USGS-10109000	Z	Mid-section	167.00	ft^3/s	2019-07-30 17:57:17+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Vegetation - Light	Good	42bc3d6c-e4ad-4364-8284-239367589a21
10	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	8ef1af85-190d-3d4c-e053-0100007f711a	00065	USGS-10109000	Z	None	2.84	ft	2019-07-30 18:06:00+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Vegetation - Light	Good	333a662b-8f54-4ccd-8537-4363131d014c
11	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	8ef1af85-190d-3d4c-e053-0100007f711a	00060	USGS-10109000	Z	Mid-section	162.00	ft^3/s	2019-07-30 18:06:00+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Vegetation - Light	Good	b295e6f9-ba33-4169-b5b6-23fd31d1daa1
12	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	92d627a0-a0f4-3689-e053-0100007f10f2	00065	USGS-10109000	Z	None	2.64	ft	2019-09-16 16:59:19+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Vegetation - Light	Good	57470ff5-62ec-4b57-a890-7da7b800f572
13	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	92d627a0-a0f4-3689-e053-0100007f10f2	00060	USGS-10109000	Z	Mid-section	126.00	ft^3/s	2019-09-16 16:59:19+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Vegetation - Light	Good	f4e2cd33-b381-407c-9ee8-22db02070f0e
14	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	9603d708-a28c-04b1-e053-0100007f2a41	00065	USGS-10109000	Z	None	2.64	ft	2019-10-28 19:06:42+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	0604fa0f-f534-4c10-9633-4357d10cb4eb
15	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	9603d708-a28c-04b1-e053-0100007f2a41	00060	USGS-10109000	Z	Mid-section	133.00	ft^3/s	2019-10-28 19:06:42+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	be6103a6-19f5-457f-8001-e08b1faa54fa
16	POINT (-111.78398 41.74355)	ab1a7c00-5751-4c9a-9c79-9abeb38a4531	92b3d616-e8fb-4f7f-862d-632f6ad1c26b	00065	USGS-10109000	Z	None	2.60	ft	2019-12-03 20:53:15+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	75a0c30d-0ed6-45e6-a0f8-0c3aa67627ef
17	POINT (-111.78398 41.74355)	3d14a129-455f-4280-aa2d-ff8106cbe102	92b3d616-e8fb-4f7f-862d-632f6ad1c26b	00060	USGS-10109000	Z	Mid-section	122.00	ft^3/s	2019-12-03 20:53:15+00:00	None	None	Approved	USGS	2026-05-24 02:13:47.380028+00:00	Clear	Good	8b39c37e-461c-452e-bfc9-a8ef50818381

Example 3: Get all of the field measurements for multiple monitoring locations

[8]:

measurements3 = waterdata.get_field_measurements(monitoring_location_id=["USGS-01594440", "USGS-040851325"])
print("Retrieved " + str(len(measurements3[0])) + " data values.")
display(measurements3[0])

Retrieving: field-measurements · 1 page · 976 rows

Retrieved 976 data values.

	geometry	field_measurements_series_id	field_visit_id	parameter_code	monitoring_location_id	observing_procedure_code	observing_procedure	value	unit_of_measure	time	qualifier	vertical_datum	approval_status	measuring_agency	last_modified	control_condition	measurement_rated	field_measurement_id
0	POINT (-76.69369 38.95592)	61b6cb68-e338-4dfd-9618-d64e9bdc64be	53fb2a20-7b79-4148-e053-0100007f46df	00065	USGS-01594440	Z	None	3.11	ft	1955-04-07 19:05:00+00:00	None	None	Approved	USGS	2026-05-22 11:05:41.715713+00:00	Clear	Good	4b1b4d58-f507-48e9-a4ba-77f6e722d8bb
1	POINT (-76.69369 38.95592)	c296b625-80d8-4ee8-a14b-f9bdaf158468	53fb2a20-7b79-4148-e053-0100007f46df	00060	USGS-01594440	Z	Unspecified	152.00	ft^3/s	1955-04-07 19:05:00+00:00	None	None	Approved	USGS	2026-05-22 11:05:41.715713+00:00	Clear	Good	845573db-b7cb-4db6-b0fb-1ea3667d89d8
2	POINT (-76.69369 38.95592)	61b6cb68-e338-4dfd-9618-d64e9bdc64be	53fb2518-fafa-3f15-e053-0100007fbbce	00065	USGS-01594440	Z	None	2.76	ft	1955-05-04 21:05:00+00:00	None	None	Approved	USGS	2026-05-22 11:05:41.715713+00:00	Clear	Fair	62218c9c-82a5-46c2-91e1-443fb88cd76b
3	POINT (-76.69369 38.95592)	c296b625-80d8-4ee8-a14b-f9bdaf158468	53fb2518-fafa-3f15-e053-0100007fbbce	00060	USGS-01594440	Z	Unspecified	127.00	ft^3/s	1955-05-04 21:05:00+00:00	None	None	Approved	USGS	2026-05-22 11:05:41.715713+00:00	Clear	Fair	b752e796-671e-4791-bd57-1bf8a2e8d27b
4	POINT (-76.69369 38.95592)	61b6cb68-e338-4dfd-9618-d64e9bdc64be	53fb2a2a-6d26-3f11-e053-0100007f0ef5	00065	USGS-01594440	Z	None	4.26	ft	1955-06-10 13:35:00+00:00	None	None	Approved	USGS	2026-05-22 11:05:41.715713+00:00	Clear	Good	d6f4cbc0-bd8f-4a3a-8129-3adc73f99e7c
...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...	...
971	POINT (-76.69369 38.95592)	61b6cb68-e338-4dfd-9618-d64e9bdc64be	25d5d229-9953-4096-8c53-7f62965975a8	00065	USGS-01594440	Z	None	4.36	ft	2026-01-07 16:40:27+00:00	None	None	Approved	USGS	2026-05-22 11:05:41.715713+00:00	Clear	Fair	d771ccbd-3df7-4abb-905a-f16925c61879
972	POINT (-76.69369 38.95592)	c296b625-80d8-4ee8-a14b-f9bdaf158468	1cef619c-e54c-4d50-8f72-8a7067de4e15	00060	USGS-01594440	Z	Acoustic Doppler Current Profiler	219.00	ft^3/s	2026-03-23 15:23:18+00:00	None	None	Provisional	USGS	2026-05-22 11:05:41.715713+00:00	Debris - Light	Fair	681c20fe-eb51-4ad1-9990-62494ec0e43a
973	POINT (-76.69369 38.95592)	61b6cb68-e338-4dfd-9618-d64e9bdc64be	1cef619c-e54c-4d50-8f72-8a7067de4e15	00065	USGS-01594440	Z	None	4.99	ft	2026-03-23 15:23:18+00:00	None	None	Provisional	USGS	2026-05-22 11:05:41.715713+00:00	Debris - Light	Fair	f7ef53bd-e01c-4705-8d39-95a1e6eeffde
974	POINT (-76.69369 38.95592)	c296b625-80d8-4ee8-a14b-f9bdaf158468	53cd995f-745d-4342-bbb8-2c3a294fc56a	00060	USGS-01594440	Z	Acoustic Doppler Current Profiler	121.00	ft^3/s	2026-05-20 15:33:18+00:00	None	None	Provisional	USGS	2026-05-22 11:05:41.715713+00:00	Clear	Fair	0411981d-bf8f-4c57-9aea-9b9e537ebbee
975	POINT (-76.69369 38.95592)	61b6cb68-e338-4dfd-9618-d64e9bdc64be	53cd995f-745d-4342-bbb8-2c3a294fc56a	00065	USGS-01594440	Z	None	4.24	ft	2026-05-20 15:33:18+00:00	None	None	Provisional	USGS	2026-05-22 11:05:41.715713+00:00	Clear	Fair	74e911ed-5c5f-4441-8124-19c27af210c3

976 rows × 18 columns

USGS dataretrieval Python Package get_field_measurements() Examples

Install the Package

Basic Usage

Interpreting the Result

Additional Examples

USGS dataretrieval Python Package `get_field_measurements()` Examples