USGS dataretrieval Python Package Surface-Water 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+gdff162cbd)
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.18)
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,918 rows
No API key detected — register for higher rate limits at https://api.waterdata.usgs.gov/signup/
Retrieved 1918 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 reading_type field_visit_id parameter_code monitoring_location_id observing_procedure_code observing_procedure value unit_of_measure ... approval_status measuring_agency last_modified control_condition measurement_rated year month day time_of_day field_measurement_id
0 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 4cd21ba9-8644-ebfc-e053-0100007fd6db 00060 USGS-10109000 Z Unspecified 17.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Excellent 1951 9 6 16:40:00+00:00 171d94e4-8989-4948-9ebd-42037d03e464
1 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 4cd21ba9-8644-ebfc-e053-0100007fd6db 00065 USGS-10109000 Z None 0.94 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Excellent 1951 9 6 16:40:00+00:00 a6764889-4d58-4f83-8e20-d6fde4a5e4e5
2 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 4cd21977-d55d-efa9-e053-0100007fcc60 00060 USGS-10109000 Z Unspecified 12.50 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Unspecified 1951 12 13 19:10:00+00:00 28b847e8-45ac-4643-a4ff-55931b008de4
3 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 4cd21977-d55d-efa9-e053-0100007fcc60 00065 USGS-10109000 Z None 0.88 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Unspecified 1951 12 13 19:10:00+00:00 891e4d38-b26b-4bd9-a664-8446c916f6b4
4 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 4cd21ba9-8645-ebfc-e053-0100007fd6db 00065 USGS-10109000 Z None 1.80 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 1952 4 23 17:25:00+00:00 8803ac0a-5a2e-4538-ac50-8a23b3867e42
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
1913 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 98c59f70-ce2c-4a4d-9acf-18a179a96c78 00065 USGS-10109000 Z None 3.11 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2026 4 20 16:31:59+00:00 54242802-9af6-41bb-9959-967334b06e20
1914 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 6e48b7b6-152b-4a98-a974-87adf3d0ddc8 00060 USGS-10109000 Z Acoustic Doppler Current Profiler 354.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Fair 2026 5 12 20:07:07+00:00 d9997123-e13c-4281-8578-8e5b012d3461
1915 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 6e48b7b6-152b-4a98-a974-87adf3d0ddc8 00065 USGS-10109000 Z None 3.38 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Fair 2026 5 12 20:07:07+00:00 f27dc6d2-0962-472e-a1e6-eff975dde0f5
1916 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 20adb970-eb0a-4892-b5f2-92e7d1678b73 00065 USGS-10109000 Z None 3.28 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2026 5 26 23:39:33+00:00 4f1c3cdd-7012-4420-8389-d56dab84c507
1917 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 20adb970-eb0a-4892-b5f2-92e7d1678b73 00060 USGS-10109000 Z Acoustic Doppler Current Profiler 321.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2026 5 26 23:39:33+00:00 d81ddc27-7142-4241-9452-c306700edd13

1918 rows × 23 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
reading_type                                    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
year                                          int64
month                                         int64
day                                           int64
time_of_day                                     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 reading_type field_visit_id parameter_code monitoring_location_id observing_procedure_code observing_procedure value unit_of_measure ... approval_status measuring_agency last_modified control_condition measurement_rated year month day time_of_day field_measurement_id
0 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 80a47f55-5d75-9c33-e053-0100007fa04d 00065 USGS-10109000 Z None 2.43 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 1 29 19:57:30+00:00 6bdeaecd-a7aa-4be0-bff2-e6c5ef2df404
1 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 80a47f55-5d75-9c33-e053-0100007fa04d 00060 USGS-10109000 Z Mid-section 83.80 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 1 29 19:57:30+00:00 ca56f390-44e2-4ac9-a038-f7427f1310f3
2 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 83ebd5c5-373c-5a52-e053-0100007f5e38 00065 USGS-10109000 Z None 2.46 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 3 11 19:29:30+00:00 78cb7375-25e4-4ac6-8e9a-c8c1a55844f0
3 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 83ebd5c5-373c-5a52-e053-0100007f5e38 00060 USGS-10109000 Z Mid-section 94.20 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 3 11 19:29:30+00:00 a498deb9-40a0-4a8e-a5e8-86dce988995d
4 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 873f3a85-f698-41b8-e053-0100007fc351 00065 USGS-10109000 Z None 3.29 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 4 23 21:39:16+00:00 631ffc3c-d80c-4704-b126-8729e63c906c
5 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 873f3a85-f698-41b8-e053-0100007fc351 00060 USGS-10109000 Z Acoustic Doppler Current Profiler 337.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 4 23 21:39:16+00:00 71cede54-6330-4413-9a10-380cd8f2ee78
6 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 8b3913bf-9253-4f4f-e053-0100007f3ec4 00060 USGS-10109000 Z Mid-section 709.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 6 12 14:02:56+00:00 98d24fbd-2c9f-4f1a-a3be-571d27e9a441
7 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 8b3913bf-9253-4f4f-e053-0100007f3ec4 00065 USGS-10109000 Z None 4.09 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 6 12 14:02:56+00:00 ef5d6df8-8081-4e39-930e-40cc190aa9b6
8 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 8ef1af85-190d-3d4c-e053-0100007f711a 00065 USGS-10109000 Z None 2.84 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Vegetation - Light Good 2019 7 30 17:57:17+00:00 2d379146-bd65-4a8c-a868-665a10c933be
9 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 8ef1af85-190d-3d4c-e053-0100007f711a 00060 USGS-10109000 Z Mid-section 167.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Vegetation - Light Good 2019 7 30 17:57:17+00:00 41ef994d-6896-4fd9-b31c-d7284e4e32eb
10 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 8ef1af85-190d-3d4c-e053-0100007f711a 00060 USGS-10109000 Z Mid-section 162.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Vegetation - Light Good 2019 7 30 18:06:00+00:00 44659028-4656-4d92-a89a-aa44e2f0ea78
11 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 8ef1af85-190d-3d4c-e053-0100007f711a 00065 USGS-10109000 Z None 2.84 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Vegetation - Light Good 2019 7 30 18:06:00+00:00 4f7bb602-4112-4249-9ccf-5dc49e52428f
12 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 92d627a0-a0f4-3689-e053-0100007f10f2 00060 USGS-10109000 Z Mid-section 126.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Vegetation - Light Good 2019 9 16 16:59:19+00:00 17b797f6-7135-4c19-a1a1-78272482ba38
13 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 92d627a0-a0f4-3689-e053-0100007f10f2 00065 USGS-10109000 Z None 2.64 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Vegetation - Light Good 2019 9 16 16:59:19+00:00 e5b5f085-a98e-489a-87e1-36024bb9dca6
14 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 9603d708-a28c-04b1-e053-0100007f2a41 00060 USGS-10109000 Z Mid-section 133.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 10 28 19:06:42+00:00 5fab5973-e8eb-4ef9-a65c-31d2c5898198
15 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 9603d708-a28c-04b1-e053-0100007f2a41 00065 USGS-10109000 Z None 2.64 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 10 28 19:06:42+00:00 a93eecf4-982b-4c7e-9ad0-22278bb9030f
16 POINT (-111.78398 41.74355) 7d5b4004-ca7e-46c5-9bde-25d5dde481c8 Discharge 92b3d616-e8fb-4f7f-862d-632f6ad1c26b 00060 USGS-10109000 Z Mid-section 122.00 ft^3/s ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 12 3 20:53:15+00:00 329fff59-5f9d-4567-afc8-96dbbde2e885
17 POINT (-111.78398 41.74355) 442c040d-8a0f-43e8-b4c7-840b2a60a89a MeanGageHeight 92b3d616-e8fb-4f7f-862d-632f6ad1c26b 00065 USGS-10109000 Z None 2.60 ft ... Approved USGS 2026-06-03 22:25:57.846799+00:00 Clear Good 2019 12 3 20:53:15+00:00 6f5f04d1-5473-4e44-bba3-3c90c8e6c591

18 rows × 23 columns

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 · 980 rows
Retrieved 980 data values.
geometry field_measurements_series_id reading_type field_visit_id parameter_code monitoring_location_id observing_procedure_code observing_procedure value unit_of_measure ... approval_status measuring_agency last_modified control_condition measurement_rated year month day time_of_day field_measurement_id
0 POINT (-76.69369 38.95592) af34921e-31ca-46f0-afad-731e7ab10cae Discharge 53fb2a20-7b79-4148-e053-0100007f46df 00060 USGS-01594440 Z Unspecified 152.00 ft^3/s ... Approved USGS 2026-06-11 12:25:29.250421+00:00 Clear Good 1955 4 7 19:05:00+00:00 4e550f30-3da4-4729-b36b-788ae2cf9680
1 POINT (-76.69369 38.95592) 10f75368-e5d4-4b6a-a4a7-ec3f00f906b7 MeanGageHeight 53fb2a20-7b79-4148-e053-0100007f46df 00065 USGS-01594440 Z None 3.11 ft ... Approved USGS 2026-06-11 12:25:29.250421+00:00 Clear Good 1955 4 7 19:05:00+00:00 93aee83d-c391-4422-be34-b6e4144b525c
2 POINT (-76.69369 38.95592) 10f75368-e5d4-4b6a-a4a7-ec3f00f906b7 MeanGageHeight 53fb2518-fafa-3f15-e053-0100007fbbce 00065 USGS-01594440 Z None 2.76 ft ... Approved USGS 2026-06-11 12:25:29.250421+00:00 Clear Fair 1955 5 4 21:05:00+00:00 2a13de67-5ffe-4923-a183-4a67741b1bd4
3 POINT (-76.69369 38.95592) af34921e-31ca-46f0-afad-731e7ab10cae Discharge 53fb2518-fafa-3f15-e053-0100007fbbce 00060 USGS-01594440 Z Unspecified 127.00 ft^3/s ... Approved USGS 2026-06-11 12:25:29.250421+00:00 Clear Fair 1955 5 4 21:05:00+00:00 73321d7b-a26f-46cc-9392-e79fad41a36c
4 POINT (-76.69369 38.95592) af34921e-31ca-46f0-afad-731e7ab10cae Discharge 53fb2a2a-6d26-3f11-e053-0100007f0ef5 00060 USGS-01594440 Z Unspecified 310.00 ft^3/s ... Approved USGS 2026-06-11 12:25:29.250421+00:00 Clear Good 1955 6 10 13:35:00+00:00 080b011e-91b9-4c77-af83-c49c59a48562
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
975 POINT (-76.69369 38.95592) af34921e-31ca-46f0-afad-731e7ab10cae Discharge 53cd995f-745d-4342-bbb8-2c3a294fc56a 00060 USGS-01594440 Z Acoustic Doppler Current Profiler 121.00 ft^3/s ... Provisional USGS 2026-06-11 12:25:29.250421+00:00 Clear Fair 2026 5 20 15:33:18+00:00 b155341c-9eb0-4d89-a82c-7a825769eb5c
976 POINT (-76.69369 38.95592) 10f75368-e5d4-4b6a-a4a7-ec3f00f906b7 MeanGageHeight 0f32679d-5358-4d28-9ed9-6900c09f1b81 00065 USGS-01594440 Z None 4.23 ft ... Provisional USGS 2026-06-11 12:25:29.250421+00:00 Clear Fair 2026 6 10 17:19:17+00:00 0a7a8ee3-3606-4075-9599-210f899afacb
977 POINT (-76.69369 38.95592) af34921e-31ca-46f0-afad-731e7ab10cae Discharge 0f32679d-5358-4d28-9ed9-6900c09f1b81 00060 USGS-01594440 Z Acoustic Doppler Current Profiler 124.00 ft^3/s ... Provisional USGS 2026-06-11 12:25:29.250421+00:00 Clear Fair 2026 6 10 17:19:17+00:00 888d6076-ae7b-496d-b4bb-edfb3a091d63
978 POINT (-76.69369 38.95592) af34921e-31ca-46f0-afad-731e7ab10cae Discharge 0f32679d-5358-4d28-9ed9-6900c09f1b81 00060 USGS-01594440 Z Acoustic Doppler Current Profiler 124.00 ft^3/s ... Provisional USGS 2026-06-11 12:25:29.250421+00:00 Clear Fair 2026 6 10 18:18:21+00:00 5d6e6e9b-4eaa-42ef-b9ba-4535d012d8a9
979 POINT (-76.69369 38.95592) 10f75368-e5d4-4b6a-a4a7-ec3f00f906b7 MeanGageHeight 0f32679d-5358-4d28-9ed9-6900c09f1b81 00065 USGS-01594440 Z None 4.25 ft ... Provisional USGS 2026-06-11 12:25:29.250421+00:00 Clear Fair 2026 6 10 18:18:21+00:00 e6a81b16-42cf-498d-bc06-53ac5e52fb55

980 rows × 23 columns