Skip to content

Commit f9df46f

Browse files
ehinmanehinman
committed
add initial samples data info
1 parent baa65e5 commit f9df46f

1 file changed

Lines changed: 213 additions & 0 deletions

File tree

‎dataretrieval/samples.py‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
"""
2+
Tool for downloading data from the Water Quality Portal (https://waterqualitydata.us)
3+
4+
See https://waterqualitydata.us/webservices_documentation for API reference
5+
6+
.. todo::
7+
8+
- implement other services like Organization, Activity, etc.
9+
10+
"""
11+
12+
from __future__ import annotations
13+
14+
import warnings
15+
from io import StringIO
16+
from typing import TYPE_CHECKING
17+
18+
import pandas as pd
19+
20+
#from .utils import BaseMetadata, query
21+
22+
if TYPE_CHECKING:
23+
from pandas import DataFrame
24+
25+
BASE_URL = "https://api.waterdata.usgs.gov/samples-data/"
26+
27+
services_dict = {
28+
"results" : ["fullphyschem", "basicphyschem",
29+
"fullbio", "basicbio", "narrow",
30+
"resultdetectionquantitationlimit",
31+
"labsampleprep", "count"],
32+
"locations" : ["site", "count"],
33+
"activities" : ["sampact", "actmetric",
34+
"actgroup", "count"],
35+
"projects" : ["project", "projectmonitoringlocationweight"],
36+
"organizations" : ["organization", "count"]
37+
}
38+
39+
40+
def _check_profiles(
41+
service,
42+
profile
43+
):
44+
"""Check that services are paired correctly with profile in
45+
a service call.
46+
47+
Parameters
48+
----------
49+
service : string
50+
One of the service names from the "services" list.
51+
profile : string
52+
One of the profile names from "results_profiles",
53+
"locations_profiles", "activities_profiles",
54+
"projects_profiles" or "organizations_profiles".
55+
"""
56+
57+
if service not in services_dict.keys():
58+
raise TypeError(
59+
f"{service} is not a Samples service. "
60+
f"Valid options are {list(services_dict.keys())}."
61+
)
62+
if profile not in services_dict[service]:
63+
raise TypeError(
64+
f"{profile} is not a profile associated with "
65+
f"the {service} service. Valid options are "
66+
f"{services_dict[service]}."
67+
)
68+
69+
def get_USGS_samples(
70+
service="results",
71+
profile="fullphyschem",
72+
activityMediaName=None,
73+
activityStartDateLower=None,
74+
activityStartDateUpper=None,
75+
activityTypeCode=None,
76+
characteristicGroup=None,
77+
characteristc=None,
78+
characteristicUserSupplied=None,
79+
boundingBox=None,
80+
countryFips=None,
81+
stateFips=None,
82+
countyFips=None,
83+
siteTypeCode=None,
84+
siteTypeName=None,
85+
usgsPCode=None,
86+
hydrologicUnit=None,
87+
monitoringLocationIdentifier=None,
88+
organizationIdentifier=None,
89+
pointLocationLatitude=None,
90+
pointLocationLongitude=None,
91+
pointLocationWithinMiles=None,
92+
projectIdentifier=None,
93+
recordIdentifierUserSupplied=None
94+
):
95+
"""Search Samples database for USGS water quality data.
96+
This is a wrapper function for the Samples database API. All potential
97+
filters are provided as arguments to the function, but please do not
98+
populate all possible filters; leave as many as feasible with their default
99+
value (None). This is important because overcomplicated web service queries
100+
can bog down the database's ability to return an applicable dataset before
101+
it times out.
102+
103+
The web GUI for the Samples database can be found here:
104+
https://waterdata.usgs.gov/download-samples/#dataProfile=site
105+
106+
If you would like more details on feasible query parameters (complete with
107+
examples), please visit the Samples database swagger docs, here:
108+
https://api.waterdata.usgs.gov/samples-data/docs#/
109+
110+
Parameters
111+
----------
112+
service : string
113+
One of the available Samples services: "results", "locations", "activities",
114+
"projects", or "organizations". Defaults to "results".
115+
profile : string
116+
One of the available profiles associated with a service. Options for each
117+
service are:
118+
"results" - "fullphyschem", "basicphyschem",
119+
"fullbio", "basicbio", "narrow",
120+
"resultdetectionquantitationlimit",
121+
"labsampleprep", "count"
122+
"locations" - "site", "count"
123+
"activities" - "sampact", "actmetric",
124+
"actgroup", "count"
125+
"projects" - "project", "projectmonitoringlocationweight"
126+
"organizations" - "organization", "count"
127+
activityMediaName : string or list of strings, optional
128+
Name or code indicating environmental medium sample was taken.
129+
Example: "Water".
130+
activityStartDateLower : string, optional
131+
The start date if using a date range. Takes the format YYYY-MM-DD.
132+
The logic is inclusive, i.e. it will also return results that
133+
match the date.
134+
activityStartDateUpper : string, optional
135+
The end date if using a date range. Takes the format YYYY-MM-DD.
136+
The logic is inclusive, i.e. it will also return results that
137+
match the date. If left as None, will pull all data before
138+
activityStartDateLower up to the most recent available results.
139+
activityTypeCode : string or list of strings, optional
140+
Text code that describes type of field activity performed.
141+
Example: "Sample-Routine, regular".
142+
characteristicGroup : string or list of strings, optional
143+
Characteristic group is a broad category describing one or more
144+
of results.
145+
Example: "Organics, PFAS"
146+
characteristc : string or list of strings, optional
147+
Characteristic is a specific category describing one or more results.
148+
Example: "Suspended Sediment Discharge"
149+
characteristicUserSupplied : string or list of strings, optional
150+
A user supplied characteristic name describing one or more results.
151+
boundingBox: list of four floats, optional
152+
Filters on the the associated monitoring location's point location
153+
by checking if it is located within the specified geographic area.
154+
The logic is inclusive, i.e. it will include locations that overlap
155+
with the edge of the bounding box. Values are separated by commas,
156+
expressed in decimal degrees, NAD83, and longitudes west of Greenwich
157+
are negative.
158+
The format is a string consisting of:
159+
- Western-most longitude
160+
- Southern-most latitude
161+
- Eastern-most longitude
162+
- Northern-most longitude
163+
Example: [-92.8,44.2,-88.9,46.0]
164+
countryFips : string or list of strings, optional
165+
Example: "US" (United States)
166+
stateFips : string or list of strings, optional
167+
Check out the code service for FIPS codes:
168+
https://api.waterdata.usgs.gov/samples-data/codeservice/docs#/
169+
Example: "US:15" (United States: Hawaii)
170+
countyFips : string or list of strings, optional
171+
Check out the code service for FIPS codes:
172+
https://api.waterdata.usgs.gov/samples-data/codeservice/docs#/
173+
Example: "US:15:001" (United States: Hawaii, Hawaii County)
174+
siteTypeCode : string or list of strings, optional
175+
An abbreviation for a certain site type.
176+
Example: "GW" (Groundwater site)
177+
siteTypeName : string or list of strings, optional
178+
A full name for a certain site type.
179+
Example: "Well"
180+
usgsPCode : string or list of strings, optional
181+
5-digit number used in the US Geological Survey computerized
182+
data system, National Water Information System (NWIS), to
183+
uniquely identify a specific constituent
184+
Example: "00060" (Discharge, cubic feet per second)
185+
hydrologicUnit : string or list of strings, optional
186+
Max 12-digit number used to describe a hydrologic unit.
187+
Example: "070900020502"
188+
monitoringLocationIdentifier : string or list of strings, optional
189+
A monitoring location identifier has two parts: the agency code
190+
and the location number, separated by a dash (-).
191+
Example: "USGS-040851385"
192+
organizationIdentifier : string or list of strings, optional
193+
Designator used to uniquely identify a specific organization.
194+
Currently only accepting the organization "USGS".
195+
pointLocationLatitude : float, optional
196+
Latitude for a point/radius query (decimal degrees). Must be used
197+
with pointLocationLongitude and pointLocationWithinMiles.
198+
pointLocationLongitude : float, optional
199+
Longitude for a point/radius query (decimal degrees). Must be used
200+
with pointLocationLatitude and pointLocationWithinMiles.
201+
pointLocationWithinMiles : float, optional
202+
Radius for a point/radius query. Must be used with
203+
pointLocationLatitude and pointLocationLongitude
204+
projectIdentifier : string or list of strings, optional
205+
Designator used to uniquely id a data collection project in
206+
organization context.
207+
recordIdentifierUserSupplied : string or list of strings, optional
208+
Internal AQS record identifier that returns 1 entry. Only available
209+
for the "results" service.
210+
"""
211+
_check_profiles(service, profile)
212+
213+

0 commit comments

Comments
 (0)