USGS Reference Lists

get_reference_table returns the metadata “reference” tables for the USGS Water Data API. These tables enumerate the allowable values for the filter arguments used elsewhere in the waterdata module — for example, the site-types table lists every valid site_type_code, and parameter-codes lists every valid parameter_code.

get_reference_table returns a (data, metadata) tuple.

[1]:

from typing import get_args

from IPython.display import Markdown, display

from dataretrieval import waterdata
from dataretrieval.waterdata.types import METADATA_COLLECTIONS

collections = list(get_args(METADATA_COLLECTIONS))
collections

[1]:

['agency-codes',
 'altitude-datums',
 'aquifer-codes',
 'aquifer-types',
 'coordinate-accuracy-codes',
 'coordinate-datum-codes',
 'coordinate-method-codes',
 'counties',
 'hydrologic-unit-codes',
 'medium-codes',
 'national-aquifer-codes',
 'parameter-codes',
 'reliability-codes',
 'site-types',
 'states',
 'statistic-codes',
 'topographic-codes',
 'time-zone-codes']

A single reference table

Fetch one table by name. The first column is the table’s primary code (the collection name, singularized, with hyphens turned into underscores — e.g. site-types -> site_type):

[2]:

site_types, _ = waterdata.get_reference_table(collection="site-types")
print(f"{len(site_types)} rows")
site_types.head()

Retrieving: site-types · 1 page · 56 rows
No API key detected — register for higher rate limits at https://api.waterdata.usgs.gov/signup/

56 rows

[2]:
site_type site_type_primary_flag site_type_name site_type_description
0 AG Y Aggregate groundwater use An Aggregate Groundwater Withdrawal/Return sit...
1 AS Y Aggregate surface-water-use An Aggregate Surface-Water Diversion/Return si...
2 AT Y Atmosphere A site established primarily to measure meteor...
3 AW Y Aggregate water-use establishment An Aggregate Water-Use Establishment represent...
4 ES Y Estuary A coastal inlet of the sea or ocean; esp. the ...

You can also pass a query to retrieve a subset — for instance specific parameter codes by id:

[3]:

some_pcodes, _ = waterdata.get_reference_table(
    collection="parameter-codes",
    query={"id": "00060,00065,00010"},
)
some_pcodes[["parameter_code", "parameter_name", "unit_of_measure"]]

Retrieving: parameter-codes · 1 page · 3 rows

[3]:
parameter_code parameter_name unit_of_measure
0 00010 Temperature, water deg C
1 00060 Discharge ft3/s
2 00065 Gage height ft

All reference tables

The full set of collections is enumerated in METADATA_COLLECTIONS. Below we preview the first few rows of each. (Most are small lookup tables; a couple — notably parameter-codes and hydrologic-unit-codes — are large, so we only display the head.)

[4]:

for collection in collections:
    df, _ = waterdata.get_reference_table(collection=collection)
    preview = df.drop(columns="geometry") if "geometry" in df.columns else df
    display(Markdown(f"### `{collection}`  \n{len(df):,} rows"))
    display(preview.head(3))

Retrieving: agency-codes · 1 page · 738 rows

agency-codes

738 rows

agency_code agency_name
0 AK001 Alaska Department of Transportation and Public...
1 AK002 Alaska Department of Environmental Conservation
2 AK004 Alaska Department of Natural Resources (DNR) 
Retrieving: altitude-datums · 1 page · 14 rows

altitude-datums

14 rows

altitude_datum altitude_datum_description
0 ASVD02 American Samoa Vertical Datum of 2002
1 BARGECANAL New York State Barge Canal datum
2 GUVD04 Guam Vertical Datum of 2004 
Retrieving: aquifer-codes · 1 page · 8,856 rows

aquifer-codes

8,856 rows

aquifer_code aquifer_name
0 000AARF Amphibolite and Amphibolite Rich Foliats
1 000AMPB Amphibolite
2 000ANRS Anorthosite 
Retrieving: aquifer-types · 1 page · 5 rows

aquifer-types

5 rows

aquifer_type aquifer_type_description
0 C Confined single aquifer
1 M Confined multiple aquifers
2 N Unconfined multiple aquifer 
Retrieving: coordinate-accuracy-codes · 1 page · 13 rows

coordinate-accuracy-codes

13 rows

coordinate_accuracy_code coordinate_accuracy_description
0 1 Accurate to + or - .1 sec (Differentially-Corr...
1 5 Accurate to + or - .5 sec (PLGR/PPS GPS).
2 B Level 1 survey-grade GPS 
Retrieving: coordinate-datum-codes · 1 page · 327 rows

coordinate-datum-codes

327 rows

coordinate_datum_code coordinate_datum_description
0 ABIDJAN Cote d'Ivoire
1 ACCRA Ghana
2 ADINDAN Description 
Retrieving: coordinate-method-codes · 1 page · 14 rows

coordinate-method-codes

14 rows

coordinate_method_code coordinate_method_description
0 C Calculated from land net
1 D Differential Global Positioning System (DGPS)
2 F Survey-grade Global positioning system (SGPS) 
Retrieving: counties · 1 page · 3,678 rows

counties

3,678 rows

county country_code state_fips_code county_fips_code county_name
0 AD-00-000 AD 00 000 Unspecified
1 AE-00-000 AE 00 000 Unspecified
2 AF-00-000 AF 00 000 Unspecified 
Retrieving: hydrologic-unit-codes · 3 pages · 125,119 rows

hydrologic-unit-codes

125,119 rows

hydrologic_unit_code hydrologic_unit_name hydrologic_unit_classification_code
0 01 New England Region R
1 0101 St. John S
2 010100 St. John B 
Retrieving: medium-codes · 1 page · 78 rows

medium-codes

78 rows

medium_code medium_name medium_description legacy_medium_code
0 AA Air Sample of atmospheric gases. *
1 AAQ QC sample - Air QC sample - Sample of atmospheric gases. [
2 AG Geologic Gases Gases originating from a geologic formation or... NaN 
Retrieving: national-aquifer-codes · 1 page · 67 rows

national-aquifer-codes

67 rows

national_aquifer_code national_aquifer_name
0 N100AKUNCD Alaska unconsolidated-deposit aquifers
1 N100ALLUVL Alluvial aquifers
2 N100BSNRGB Basin and Range basin-fill aquifers 
Retrieving: parameter-codes · 1 page · 19,675 rows

parameter-codes

19,675 rows

parameter_code parameter_name unit_of_measure parameter_group_code parameter_description medium statistical_basis time_basis weight_basis particle_size_basis sample_fraction temperature_basis epa_equivalence
0 00001 Xsec loc, US from rb ft INF Location in cross section, distance from right... NaN NaN NaN NaN NaN NaN NaN Agree
1 00002 Xsec loc, US from rb % INF Location in cross section, distance from right... NaN NaN NaN NaN NaN NaN NaN Agree
2 00003 Sampling depth ft INF Sampling depth, feet NaN NaN NaN NaN NaN NaN NaN Agree 
Retrieving: reliability-codes · 1 page · 4 rows

reliability-codes

4 rows

reliability_code reliability_description
0 C Data have been field checked by the reporting ...
1 L Location not accurate.
2 M Minimal data. 
Retrieving: site-types · 1 page · 56 rows

site-types

56 rows

site_type site_type_primary_flag site_type_name site_type_description
0 AG Y Aggregate groundwater use An Aggregate Groundwater Withdrawal/Return sit...
1 AS Y Aggregate surface-water-use An Aggregate Surface-Water Diversion/Return si...
2 AT Y Atmosphere A site established primarily to measure meteor... 
Retrieving: states · 1 page · 398 rows

states

398 rows

state country_code state_fips_code state_name state_postal_code
0 AD-00 AD 00 Unspecified NaN
1 AE-00 AE 00 Unspecified NaN
2 AF-00 AF 00 Unspecified NaN 
Retrieving: statistic-codes · 1 page · 3,188 rows

statistic-codes

3,188 rows

statistic_code statistic_name statistic_description
0 00001 MAXIMUM MAXIMUM VALUES
1 00002 MINIMUM MINIMUM VALUES
2 00003 MEAN MEAN VALUES 
Retrieving: topographic-codes · 1 page · 18 rows

topographic-codes

18 rows

topographic_code topography_name short_topography_description full_topography_description
0 A Alluvial fan Stream deposit of loose rock material where it... Alluvial fan refers to a low, outspread, relat...
1 B Playa Undrained desert basin in which water accumula... Playa refers to a dried-up, vegetation-free, f...
2 C Stream channel Bed in which a natural stream of water runs. Stream refers to the bed in which a natural st... 
Retrieving: time-zone-codes · 1 page · 53 rows

time-zone-codes

53 rows

time_zone_code time_zone_name time_zone_description time_zone_utc_offset time_zone_daylight_savings_time_code time_zone_daylight_savings_time_name time_zone_daylight_savings_utc_offset
0 ACST Central Australia Standard Time Central Australia +09:30 ACSST Central Australia Summer Time +10:30
1 AEST Australia Eastern Standard Time Eastern Australia +10:00 AESST Australia Eastern Summer Time +11:00
2 AFT Afghanistan Time Afghanistan +04:30 NaN NaN NaN

More help