This page was generated from things.ipynb. Interactive online version: Binder badge

SensorThings#

[1]:

from __future__ import annotations

from pygeohydro import SensorThings

SensorThings is a recently released USGS web service that provides access to real-time USGS sensors. For more information about the service you can check out this to the service and also this which is overview or different USGS APIs. PyGeoHydro provides access to the Things endpoint which is “one of the most important components, and can be mapped to USGS Monitoring locations”.

[2]:

sensor = SensorThings()

We can query information about stations using sensor_info. We can pass a single ID or list of them.

[3]:

resp = sensor.sensor_info(["USGS-09380000", "USGS-09472050"])
resp

[3]:
@iot.id name description properties.state properties.county properties.country properties.mapScale properties.stateCode properties.agencyCode properties.countryFIPS properties.hydrologicUnit properties.decimalLatitude properties.decimalLongitude properties.monitoringLocationUrl properties.monitoringLocationName properties.monitoringLocationType properties.monitoringLocationNumber properties.locationHUCTwelveDigitCode properties.decimalLatitudeStandardized properties.decimalLongitudeStandardized
0 USGS-09380000 USGS-09380000 Stream Arizona Coconino County United States of America 24000 AZ USGS US 14070006 36.864333 -111.587872 https://waterdata.usgs.gov/monitoring-location... COLORADO RIVER AT LEES FERRY, AZ Stream 09380000 140700061105 36.864333 -111.587872
1 USGS-09472050 USGS-09472050 Stream Arizona Pima County United States of America 24000 AZ USGS US 15050203 32.446367 -110.488275 https://waterdata.usgs.gov/monitoring-location... SAN PEDRO R AT REDINGTON BRIDGE NR REDINGTON, AZ Stream 09472050 150502030503 32.446367 -110.488275 
[4]:

resp.columns

[4]:

Index(['@iot.id', 'name', 'description', 'properties.state',
       'properties.county', 'properties.country', 'properties.mapScale',
       'properties.stateCode', 'properties.agencyCode',
       'properties.countryFIPS', 'properties.hydrologicUnit',
       'properties.decimalLatitude', 'properties.decimalLongitude',
       'properties.monitoringLocationUrl', 'properties.monitoringLocationName',
       'properties.monitoringLocationType',
       'properties.monitoringLocationNumber',
       'properties.locationHUCTwelveDigitCode',
       'properties.decimalLatitudeStandardized',
       'properties.decimalLongitudeStandardized'],
      dtype='object')

Additionally, we can get a sensor property using sensor_property.

[5]:

resp = sensor.sensor_property("Datastreams", ["USGS-09380000", "USGS-09472050"])
resp

[5]:
@iot.selfLink @iot.id name description observationType phenomenonTime ObservedProperty@iot.navigationLink Sensor@iot.navigationLink Thing@iot.navigationLink Observations@iot.navigationLink unitOfMeasurement.name unitOfMeasurement.symbol unitOfMeasurement.definition observedArea.type observedArea.coordinates properties.ParameterCode properties.StatisticCode properties.WebDescription properties.Thresholds
0 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... 2995b14c17004b24894069ee6b29e487 2995b14c17004b24894069ee6b29e487 Dissolved oxygen, water, unfiltered, milligram... Instantaneous 2024-12-24T09:15:00Z/2025-01-04T00:00:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... Milligrams per Liter mg/l Point [-111.5878722, 36.8643333] 00300 00011 NaN NaN
1 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... 31e57b58f62c48f3b8391f9bae530152 31e57b58f62c48f3b8391f9bae530152 Turbidity, water, unfiltered, monochrome near ... Instantaneous 2025-01-03T06:00:00Z/2025-01-04T00:00:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... _FNU _FNU Point [-111.5878722, 36.8643333] 63680 00011 NaN NaN
2 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... 622ea8526d06489e8de89d1f4827d8b6 622ea8526d06489e8de89d1f4827d8b6 pH, water, unfiltered, field, standard units /... Instantaneous 2024-12-24T09:15:00Z/2025-01-04T00:00:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... ph Units pH Units Point [-111.5878722, 36.8643333] 00400 00011 NaN NaN
3 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... 6a001d48ca364fce846d6e4f0664d387 6a001d48ca364fce846d6e4f0664d387 Specific conductance, water, unfiltered, micro... Instantaneous 2024-12-24T09:15:00Z/2025-01-04T00:00:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... uS/cm uS/cm Point [-111.5878722, 36.8643333] 00095 00011 NaN NaN
4 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... a62122d8ff094125b63bb2f73410b2b4 a62122d8ff094125b63bb2f73410b2b4 Discharge, cubic feet per second / USGS-093800... Instantaneous 2024-12-24T09:15:00Z/2025-01-04T00:00:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... Cubic Feet per Second ft^3/s Point [-111.5878722, 36.8643333] 00060 00011 NaN NaN
5 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... b3c374548a8d4553868046dd9fda2582 b3c374548a8d4553868046dd9fda2582 Temperature, water, degrees Celsius / USGS-093... Instantaneous 2024-12-24T09:15:00Z/2025-01-04T00:00:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... Degrees Centigrade degC Point [-111.5878722, 36.8643333] 00010 00011 NaN NaN
6 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... c1d72c8390d144f78b51568a3755a5ad c1d72c8390d144f78b51568a3755a5ad None / USGS-09380000-c1d72c8390d144f78b51568a3... Instantaneous 2024-12-24T09:15:00Z/2025-01-04T00:00:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... Feet ft Point [-111.5878722, 36.8643333] 00065 00011 PRIMARY STAGE NaN
7 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... e1c4b44914ed43819cf8e2e2138e9064 e1c4b44914ed43819cf8e2e2138e9064 None / USGS-09380000-e1c4b44914ed43819cf8e2e21... Instantaneous 2024-12-24T09:15:00Z/2025-01-04T00:00:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... in in Point [-111.5878722, 36.8643333] 00045 NaN NaN NaN
8 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... 3c47927571274e388e7f4a8fbf1049e9 3c47927571274e388e7f4a8fbf1049e9 Gage height / USGS-09472050-3c47927571274e388e... Instantaneous 2024-12-24T09:15:00Z/2025-01-03T23:15:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... Feet ft Point [-110.4884183, 32.4461827] 00065 00011 NaN [{'Name': 'Operational limit (minimum) Gage he...
9 https://labs.waterdata.usgs.gov/sta/v1.1/Datas... 9e9527c7d6c542cd92a5178922712ed8 9e9527c7d6c542cd92a5178922712ed8 Discharge / USGS-09472050-9e9527c7d6c542cd92a5... Instantaneous 2024-12-24T09:15:00Z/2025-01-03T23:15:00Z https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... https://labs.waterdata.usgs.gov/sta/v1.1/Datas... Cubic Feet per Second ft^3/s Point [-110.4884183, 32.4461827] 00060 00011 NaN NaN

For more complex queries, we need to construct an Odata query.

[6]:

odata = {
    "filter": "properties/monitoringLocationType eq 'Stream' and properties/stateCode eq 'AZ'",
}
df = sensor.query_byodata(odata)
df

[6]:
@iot.selfLink @iot.id name description Locations@iot.navigationLink HistoricalLocations@iot.navigationLink Datastreams@iot.navigationLink properties.state properties.county properties.country ... properties.decimalLatitude properties.decimalLongitude properties.monitoringLocationUrl properties.monitoringLocationName properties.monitoringLocationType properties.monitoringLocationNumber properties.locationHUCTwelveDigitCode properties.decimalLatitudeStandardized properties.decimalLongitudeStandardized properties.mapScale
0 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USFS-09489082 USFS-09489082 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Greenlee County United States of America ... 33.675028 -109.270111 https://waterdata.usgs.gov/monitoring-location... NORTH FORK THOMAS CREEK NEAR ALPINE, AZ Stream 09489082 150601010107 33.675028 -109.270111 NaN
1 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USGS-09379025 USGS-09379025 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Apache County United States of America ... 36.155000 -109.537500 https://waterdata.usgs.gov/monitoring-location... CHINLE CREEK AT CHINLE, AZ Stream 09379025 140802040801 36.155000 -109.537500 24000.0
2 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USGS-09379200 USGS-09379200 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Apache County United States of America ... 36.943891 -109.710668 https://waterdata.usgs.gov/monitoring-location... CHINLE CREEK NEAR MEXICAN WATER, AZ Stream 09379200 140802041702 36.943891 -109.710668 NaN
3 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USGS-09380000 USGS-09380000 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Coconino County United States of America ... 36.864333 -111.587872 https://waterdata.usgs.gov/monitoring-location... COLORADO RIVER AT LEES FERRY, AZ Stream 09380000 140700061105 36.864333 -111.587872 24000.0
4 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USGS-09382000 USGS-09382000 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Coconino County United States of America ... 36.872210 -111.594605 https://waterdata.usgs.gov/monitoring-location... PARIA RIVER AT LEES FERRY, AZ Stream 09382000 140700070706 36.872210 -111.594605 NaN
... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ... ...
198 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USGS-331954112371801 USGS-331954112371801 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Maricopa County United States of America ... 33.331753 -112.621656 https://waterdata.usgs.gov/monitoring-location... GILA RIVER ABOVE SR-85 NEAR BUCKEYE, AZ Stream 331954112371801 150701010206 33.331753 -112.621656 24000.0
199 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USGS-332029112353701 USGS-332029112353701 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Maricopa County United States of America ... 33.341517 -112.593542 https://waterdata.usgs.gov/monitoring-location... GILA RIVER AT MILLER RD NEAR BUCKEYE, AZ Stream 332029112353701 150701010206 33.341517 -112.593542 24000.0
200 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USGS-332106112314101 USGS-332106112314101 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Maricopa County United States of America ... 33.351683 -112.528044 https://waterdata.usgs.gov/monitoring-location... GILA RIVER BELOW WATERMAN WASH NEAR BUCKEYE, AZ Stream 332106112314101 150701010109 33.351683 -112.528044 24000.0
201 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USGS-332153112022300 USGS-332153112022300 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Maricopa County United States of America ... 33.364753 -112.039797 https://waterdata.usgs.gov/monitoring-location... UNNAMED WASH AT HEARD SCOUT PUEBLO NEAR PHOENI... Stream 332153112022300 150601060306 33.364753 -112.039797 NaN
202 https://labs.waterdata.usgs.gov/sta/v1.1/Thing... USGS-364904113593701 USGS-364904113593701 Stream https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... https://labs.waterdata.usgs.gov/sta/v1.1/Thing... Arizona Mohave County United States of America ... 36.817869 -113.993589 https://waterdata.usgs.gov/monitoring-location... VIRGIN RV AT SAND HOLLOW WASH NR LITTLEFIELD, AZ Stream 364904113593701 150100100605 36.817869 -113.993589 24000.0

203 rows × 24 columns

We can get geospatial data by setting the format to geojson.

[7]:

expand = {"Locations": {"select": "location"}}
max_count = 1000
conditionals = "properties/monitoringLocationType eq 'Stream' and properties/stateCode eq 'AZ'"
odata = sensor.odata_helper(expand=expand, max_count=max_count, conditionals=conditionals)

df = sensor.query_byodata(odata, outformat="geojson")
df.explore()

[7]:
Make this Notebook Trusted to load map: File -> Trust Notebook

We can even make more complex queries. For such cases we can use the odata_helper function to contruct complex Odata filters.

[8]:

expand = {
    "ObservedProperty": {"select": "name,description,@iot.id"},
    "Observations": {
        "select": "result,phenomenonTime,@iot.id",
        "orderby": "phenomenonTime desc",
        "top": 1,
    },
}
odata_inner = sensor.odata_helper(expand=expand)

columns = ["properties", "@iot.id"]
conditionals = " and ".join(
    [
        "Datastreams/ObservedProperty/@iot.id eq '00060' ",
        "properties/monitoringLocationType eq 'Stream' ",
        "startswith(properties/hydrologicUnit,'15')",
    ]
)
expand = {
    "Locations": {"select": "name,description,location,@iot.id"},
    "Datastreams": {
        "select": "name,unitOfMeasurement,@iot.id",
        "filter": "ObservedProperty/@iot.id eq '00060'",
        "expand": odata_inner["expand"],
    },
}
max_count = 1000
odata = sensor.odata_helper(
    columns=columns,
    conditionals=conditionals,
    expand=expand,
    max_count=max_count,
)

df = sensor.query_byodata(odata, outformat="geojson")
df.explore()

[8]:
Make this Notebook Trusted to load map: File -> Trust Notebook