Sample SensorThings Queries and Responses

The SensorThings API was an experimental interface providing access to location metadata and provisional measurements from the last 10 days. After an evaluation period, we’ve decided that we won’t be promoting our SensorThings implementation to production status. The API will be formally sunset once replacement APIs are made available.

Sample Calls with Responses

List All Object Types

This request provides an overview of the SensorThings response. Each value consists of a “name” that provides the name of the SensorThings class together with a “url” that provides access to all objects of this class.

The following provides an overview of the SensorThings response at https://labs.waterdata.usgs.gov/sta/v1.1/ :

{
  "value": [
    {
      "name": "Datastreams",
      "url": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams"
    },
    {
      "name": "MultiDatastreams",
      "url": "https://labs.waterdata.usgs.gov/sta/v1.1/MultiDatastreams"
    },
    {
      "name": "FeaturesOfInterest",
      "url": "https://labs.waterdata.usgs.gov/sta/v1.1/FeaturesOfInterest"
    },
    {
      "name": "HistoricalLocations",
      "url": "https://labs.waterdata.usgs.gov/sta/v1.1/HistoricalLocations"
    },
    {
      "name": "Locations",
      "url": "https://labs.waterdata.usgs.gov/sta/v1.1/Locations"
    },
    {
      "name": "Observations",
      "url": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations"
    },
    {
      "name": "ObservedProperties",
      "url": "https://labs.waterdata.usgs.gov/sta/v1.1/ObservedProperties"
    },
    {
      "name": "Sensors",
      "url": "https://labs.waterdata.usgs.gov/sta/v1.1/Sensors"
    },
    {
      "name": "Things",
      "url": "https://labs.waterdata.usgs.gov/sta/v1.1/Things"
    }
  ],
  "serverSettings": {
    "conformance": [
      "http://www.opengis.net/spec/iot_sensing/1.1/req/batch-request/batch-request",
      "http://www.opengis.net/spec/iot_sensing/1.1/req/create-update-delete",
      "http://www.opengis.net/spec/iot_sensing/1.1/req/data-array/data-array",
      "http://www.opengis.net/spec/iot_sensing/1.1/req/datamodel",
      "http://www.opengis.net/spec/iot_sensing/1.1/req/multi-datastream",
      "http://www.opengis.net/spec/iot_sensing/1.1/req/request-data",
      "http://www.opengis.net/spec/iot_sensing/1.1/req/resource-path/resource-path-to-entities",
      "https://fraunhoferiosb.github.io/FROST-Server/extensions/DeepSelect.html",
      "https://fraunhoferiosb.github.io/FROST-Server/extensions/GeoJSON-ResultFormat.html",
      "https://fraunhoferiosb.github.io/FROST-Server/extensions/SelectDistinct.html",
      "https://github.com/INSIDE-information-systems/SensorThingsAPI/blob/master/CSV-ResultFormat/CSV-ResultFormat.md"
    ]
  }
}
}

Get All of One Type

This request provides all of one type. The types are the core classes: Locations, Things, Datastreams, Observations, ObservedProperties. To request all Things (AKA monitoring locations), use the following URL:

https://labs.waterdata.usgs.gov/sta/v1.1/Things : The SensorThings API will respond with a list of available Things as follows, including a @iot.nextLink to get the next set. For brevity, the example will limit the response to 5 :

{
  "@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things?$top=5&$skip=5",
  "value": [
    {
      "description": "Well",
      "@iot.id": "USGS-340422107370801",
      "name": "USGS-340422107370801",
      "properties": {
        "state": "New Mexico",
        "active": true,
        "agency": "U.S. Geological Survey",
        "county": "Socorro County",
        "country": "US",
        "district": "New Mexico",
        "stateFIPS": "US:35",
        "wellDepth": "285",
        "agencyCode": "USGS",
        "countyFIPS": "US:35:053",
        "countryFIPS": "US",
        "districtCode": "35",
        "localAquifer": "Datil Formation (Clastic Rocks of Volcanic Fragments)",
        "altitudeDatum": "North American Vertical Datum of 1988",
        "altitudeMethod": "Interpolated from Digital Elevation Model",
        "hydrologicUnit": "130202080209",
        "holeDepthSource": "A",
        "nationalAquifer": "Rio Grande aquifer system",
        "altitudeAccuracy": "4.3",
        "nationalAquiferCode": "S100RIOGRD",
        "monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/340422107370801",
        "monitoringLocationName": "03S.08W.01.413 VLA WELL 2",
        "monitoringLocationType": "Well",
        "monitoringLocationNumber": "340422107370801",
        "monitoringLocationAltitudeLandSurface": "6981"
      },
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-340422107370801')",
      "Datastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-340422107370801')/Datastreams",
      "MultiDatastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-340422107370801')/MultiDatastreams",
      "TaskingCapabilities@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-340422107370801')/TaskingCapabilities",
      "Locations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-340422107370801')/Locations",
      "HistoricalLocations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-340422107370801')/HistoricalLocations"
    },
    {
      "description": "Estuary",
      "@iot.id": "USGS-08077658",
      "name": "USGS-08077658",
      "properties": {
        "state": "Texas",
        "active": true,
        "agency": "U.S. Geological Survey",
        "county": "Galveston County",
        "country": "US",
        "district": "Texas",
        "stateFIPS": "US:48",
        "agencyCode": "USGS",
        "countyFIPS": "US:48:167",
        "countryFIPS": "US",
        "districtCode": "48",
        "altitudeDatum": "National Geodetic Vertical Datum of 1929",
        "altitudeMethod": "Interpolated from topographic map.",
        "hydrologicUnit": "120402040200",
        "altitudeAccuracy": "2",
        "monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/08077658",
        "monitoringLocationName": "TX City Pump Sta at Texas City, TX",
        "monitoringLocationType": "Estuary",
        "monitoringLocationNumber": "08077658",
        "monitoringLocationAltitudeLandSurface": "0"
      },
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08077658')",
      "Datastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08077658')/Datastreams",
      "MultiDatastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08077658')/MultiDatastreams",
      "TaskingCapabilities@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08077658')/TaskingCapabilities",
      "Locations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08077658')/Locations",
      "HistoricalLocations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08077658')/HistoricalLocations"
    },
    {
      "description": "Stream",
      "@iot.id": "USGS-02231175",
      "name": "USGS-02231175",
      "properties": {
        "state": "Georgia",
        "active": true,
        "agency": "U.S. Geological Survey",
        "county": "Charlton County",
        "country": "US",
        "district": "Georgia",
        "stateFIPS": "US:13",
        "agencyCode": "USGS",
        "countyFIPS": "US:13:049",
        "countryFIPS": "US",
        "districtCode": "13",
        "altitudeDatum": "North American Vertical Datum of 1988",
        "altitudeMethod": "Interpolated from topographic map.",
        "hydrologicUnit": "030702040803",
        "altitudeAccuracy": ".1",
        "monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/02231175",
        "monitoringLocationName": "ST MARYS RIVER AT FERRY LANDING NEAR FOLKSTON, GA",
        "monitoringLocationType": "Stream",
        "monitoringLocationNumber": "02231175",
        "monitoringLocationAltitudeLandSurface": "0.0"
      },
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02231175')",
      "Datastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02231175')/Datastreams",
      "MultiDatastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02231175')/MultiDatastreams",
      "TaskingCapabilities@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02231175')/TaskingCapabilities",
      "Locations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02231175')/Locations",
      "HistoricalLocations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02231175')/HistoricalLocations"
    },
    {
      "description": "Stream",
      "@iot.id": "USGS-08109310",
      "name": "USGS-08109310",
      "properties": {
        "state": "Texas",
        "active": true,
        "agency": "U.S. Geological Survey",
        "county": "Brazos County",
        "country": "US",
        "district": "Texas",
        "stateFIPS": "US:48",
        "agencyCode": "USGS",
        "countyFIPS": "US:48:041",
        "countryFIPS": "US",
        "districtCode": "48",
        "altitudeDatum": "North American Vertical Datum of 1988",
        "altitudeMethod": "Interpolated from Digital Elevation Model",
        "hydrologicUnit": "120701010702",
        "altitudeAccuracy": "1.6",
        "monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/08109310",
        "monitoringLocationName": "Thompson Ck at TX 47 nr Bryan, TX",
        "monitoringLocationType": "Stream",
        "monitoringLocationNumber": "08109310",
        "monitoringLocationAltitudeLandSurface": "230"
      },
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08109310')",
      "Datastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08109310')/Datastreams",
      "MultiDatastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08109310')/MultiDatastreams",
      "TaskingCapabilities@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08109310')/TaskingCapabilities",
      "Locations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08109310')/Locations",
      "HistoricalLocations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-08109310')/HistoricalLocations"
    },
    {
      "description": "Stream",
      "@iot.id": "USGS-02252500",
      "name": "USGS-02252500",
      "properties": {
        "state": "Florida",
        "active": true,
        "agency": "U.S. Geological Survey",
        "county": "Indian River County",
        "country": "US",
        "district": "Florida",
        "stateFIPS": "US:12",
        "agencyCode": "USGS",
        "countyFIPS": "US:12:061",
        "countryFIPS": "US",
        "districtCode": "125",
        "hydrologicUnit": "030802030303",
        "monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/02252500",
        "monitoringLocationName": "NORTH CANAL NEAR VERO BEACH, FL",
        "monitoringLocationType": "Stream",
        "monitoringLocationNumber": "02252500"
      },
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02252500')",
      "Datastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02252500')/Datastreams",
      "MultiDatastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02252500')/MultiDatastreams",
      "TaskingCapabilities@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02252500')/TaskingCapabilities",
      "Locations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02252500')/Locations",
      "HistoricalLocations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-02252500')/HistoricalLocations"
    }
  ]
}

All other object types can be accessed in the same manner using the URLs provided in the SensorThings API landing page.

Get One of a Type

This request provides information related to a specific device. In this instance, the response includes the Thing record for the famous gauge on the Colorado River at Lee’s Ferry.

In the example, one can see that the property @iot.id has the value 'USGS-09380000', adding this identifier at the end of the URL in parentheses () creates the URL for this specific thing. (Alternatively, this URL is provided in the @iot.selfLink attribute of this object):

All other object types can be directly addressed in the same manner. https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')

The response to the request for a specific object (Thing) consists of exactly this object:

{
  "description": "Stream",
  "@iot.id": "USGS-09380000",
  "name": "USGS-09380000",
  "properties": {
    "state": "Arizona",
    "active": true,
    "agency": "U.S. Geological Survey",
    "county": "Coconino County",
    "country": "US",
    "district": "Arizona",
    "stateFIPS": "US:04",
    "agencyCode": "USGS",
    "countyFIPS": "US:04:005",
    "countryFIPS": "US",
    "districtCode": "04",
    "altitudeDatum": "North American Vertical Datum of 1988",
    "altitudeMethod": "Interpolated from Digital Elevation Model",
    "hydrologicUnit": "140700061105",
    "altitudeAccuracy": "4.3",
    "monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/09380000",
    "monitoringLocationName": "COLORADO RIVER AT LEES FERRY, AZ",
    "monitoringLocationType": "Stream",
    "monitoringLocationNumber": "09380000",
    "monitoringLocationAltitudeLandSurface": "3083"
  },
  "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')",
  "Locations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')/Locations",
  "MultiDatastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')/MultiDatastreams",
  "HistoricalLocations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')/HistoricalLocations",
  "TaskingCapabilities@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')/TaskingCapabilities",
  "Datastreams@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')/Datastreams"
}

One of the strengths of the SensorThings API is the ability to easily navigate through data along the associations between types. For example, to know what Datastreams are available for a specific Thing, add the name of the Datastreams class to the end of the URL for the specific Thing. (Alternatively, this URL is provided in the “Datastreams@iot.navigationLink ” attribute of this object):

https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')/Datastreams

This request provides a list of all Datastreams (discharge, stage, temperature, and others) associated with the thing, and also includes additional metadata, such as operational limits:

{
  "value": [
    {
      "description": "Specific cond at 25C / USGS-09380000-9d24cf50257a4f60b76b92e38f286cde",
      "@iot.id": "9d24cf50257a4f60b76b92e38f286cde",
      "name": "9d24cf50257a4f60b76b92e38f286cde",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2021-07-12T18:45:00.000Z/2022-12-20T22:00:00.000Z",
      "properties": {
        "Thresholds": [
          {
            "Name": "HIGH SC THRESHOLD",
            "Type": "ThresholdAbove",
            "Periods": [
              {
                "EndTime": "9999-12-31T23:59:59.9999999+00:00",
                "StartTime": "2018-01-10T01:00:00.0000000-07:00",
                "SuppressData": true,
                "ReferenceValue": 1200
              }
            ],
            "ReferenceCode": "Operational limit - high-Public"
          },
          {
            "Name": "LOW SC THRESHOLD",
            "Type": "ThresholdBelow",
            "Periods": [
              {
                "EndTime": "9999-12-31T23:59:59.9999999+00:00",
                "StartTime": "2018-01-10T01:00:00.0000000-07:00",
                "SuppressData": true,
                "ReferenceValue": 400
              }
            ],
            "ReferenceCode": "Operational limit - low-Public"
          }
        ],
        "ParameterCode": "00095",
        "StatisticCode": "00011"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')",
      "unitOfMeasurement": {
        "name": "uS/cm",
        "symbol": "uS/cm",
        "definition": ""
      },
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/Observations",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/Sensor",
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/ObservedProperty",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/Thing"
    },
    {
      "description": "None / USGS-09380000-e1c4b44914ed43819cf8e2e2138e9064",
      "@iot.id": "e1c4b44914ed43819cf8e2e2138e9064",
      "name": "e1c4b44914ed43819cf8e2e2138e9064",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2022-01-10T01:30:00.000Z/2022-12-20T22:00:00.000Z",
      "properties": {
        "ParameterCode": "00045"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')",
      "unitOfMeasurement": {
        "name": "in",
        "symbol": "in",
        "definition": ""
      },
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/Observations",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/Sensor",
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/ObservedProperty",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/Thing"
    },
    {
      "description": "None / USGS-09380000-0a10dcb7436f4af8a679a783ae3d8d58",
      "@iot.id": "0a10dcb7436f4af8a679a783ae3d8d58",
      "name": "0a10dcb7436f4af8a679a783ae3d8d58",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2022-07-08T20:30:00.000Z/2022-07-20T19:00:00.000Z",
      "properties": {
        "ParameterCode": "00095",
        "StatisticCode": "00011",
        "WebDescription": "Starts 7/8/22"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')",
      "unitOfMeasurement": {
        "name": "uS/cm",
        "symbol": "uS/cm",
        "definition": ""
      },
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/Observations",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/Sensor",
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/ObservedProperty",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/Thing"
    },
    {
      "description": "Discharge / USGS-09380000-a62122d8ff094125b63bb2f73410b2b4",
      "@iot.id": "a62122d8ff094125b63bb2f73410b2b4",
      "name": "a62122d8ff094125b63bb2f73410b2b4",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2021-09-16T11:00:00.000Z/2022-12-20T22:00:00.000Z",
      "properties": {
        "ParameterCode": "00060",
        "StatisticCode": "00011"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')",
      "unitOfMeasurement": {
        "name": "Cubic Feet per Second",
        "symbol": "ft^3/s",
        "definition": ""
      },
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/Observations",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/Sensor",
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/ObservedProperty",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/Thing"
    },
    {
      "description": "Temperature, water / USGS-09380000-b3c374548a8d4553868046dd9fda2582",
      "@iot.id": "b3c374548a8d4553868046dd9fda2582",
      "name": "b3c374548a8d4553868046dd9fda2582",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2021-07-12T20:30:00.000Z/2022-12-20T22:00:00.000Z",
      "properties": {
        "ParameterCode": "00010",
        "StatisticCode": "00011"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')",
      "unitOfMeasurement": {
        "name": "Degrees Centigrade",
        "symbol": "degC",
        "definition": ""
      },
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/Observations",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/Sensor",
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/ObservedProperty",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/Thing"
    },
    {
      "description": "None / USGS-09380000-c1d72c8390d144f78b51568a3755a5ad",
      "@iot.id": "c1d72c8390d144f78b51568a3755a5ad",
      "name": "c1d72c8390d144f78b51568a3755a5ad",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2022-07-08T18:30:00.000Z/2022-12-20T22:00:00.000Z",
      "properties": {
        "ParameterCode": "00065",
        "StatisticCode": "00011",
        "WebDescription": "PRIMARY STAGE"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')",
      "unitOfMeasurement": {
        "name": "Feet",
        "symbol": "ft",
        "definition": ""
      },
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/Observations",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/Sensor",
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/ObservedProperty",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/Thing"
    }
  ]
}

All associations between objects can be traversed in the same manner.

Specific Attributes of an Object

Most applications do not require all attributes provided by the SensorThings API object types. While such a reduction in the breadth of the data may not seem especially relevant pertaining to one individual object, when thousands of objects are requested such reduction through filtering can vastly reduce the volume of data being transferred. This is particularly important if one is building a mobile application, which may be accessed over a shaky internet connection! In the following example, the Things response is reduced to individual devices and descriptions with the $select parameter:

https://labs.waterdata.usgs.gov/sta/v1.1/Things?$select=@iot.id,description&$top=3

{
  "@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things?$top=3&$skip=3&$select=id,description",
  "value": [
    {
      "description": "Well",
      "@iot.id": "USGS-340422107370801"
    },
    {
      "description": "Estuary",
      "@iot.id": "USGS-08077658"
    },
    {
      "description": "Stream",
      "@iot.id": "USGS-02231175"
    }
  ]
}

It is also possible to do a deep select , which is particularly useful for drilling into the properties of each component.

For example, this query returns the name and url of each Thing https://labs.waterdata.usgs.gov/sta/v1.1/Things?$select=@iot.id,properties/monitoringLocationName,properties/monitoringLocationUrl&$top=3

{
  "@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things?$top=3&$skip=3&$select=id,properties%2FmonitoringLocationName,properties%2FmonitoringLocationUrl",
  "value": [
    {
      "@iot.id": "USGS-340422107370801",
      "properties": {
        "monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/340422107370801",
        "monitoringLocationName": "03S.08W.01.413 VLA WELL 2"
      }
    },
    {
      "@iot.id": "USGS-08077658",
      "properties": {
        "monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/08077658",
        "monitoringLocationName": "TX City Pump Sta at Texas City, TX"
      }
    },
    {
      "@iot.id": "USGS-02231175",
      "properties": {
        "monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/02231175",
        "monitoringLocationName": "ST MARYS RIVER AT FERRY LANDING NEAR FOLKSTON, GA"
      }
    }
  ]
}

Sorting Responses

It is often useful to receive a dataset ordered by a specific attribute. The orderby request parameter is available for this purpose, the response dataset can be ordered in either ascending or descending order by use of asc or desc respectively.

A useful application of this request parameter is to pair it with top to get, for example, the two latest available observation values for a datastream :

https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/Observations?
	$orderby=phenomenonTime desc
	&$top=2

Combine Request Parameters

Top-level $options are separated with a &.

https://labs.waterdata.usgs.gov/sta/v1.1/Things?$expand=Locations&$top=1

Use , to separate items in a $select or $expand.

https://labs.waterdata.usgs.gov/sta/v1.1/Things?$expand=Locations,Datastreams&$top=1

Within a $expand, you use ; to separate $options. Use ( ) to clearly specify which request parameters apply to which expanded object type.

https://labs.waterdata.usgs.gov/sta/v1.1/Things?$expand=Locations($select=id,name;$top=1),Datastreams($select=name,id;$top=1)&$top=1

Build a Targeted Query

Target a response by connecting related object types within one request. A common example of this is to provide all Things together with all Datastreams associated with each of the Things. Building on the example above, add all Datastreams to each of the slimmed-down Things described above, by adding the $expand request parameter to the URL:

https://labs.waterdata.usgs.gov/sta/v1.1/Things?$select=@iot.id,description&$expand=Datastreams&$top=2

This request provides the identifier and description of each Thing , together with all Datastreams associated with each Thing:

{
  "@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things?$top=2&$skip=2&$select=id,description&$expand=Datastreams",
  "value": [
    {
      "description": "Well",
      "@iot.id": "USGS-340422107370801",
      "Datastreams": [
        {
          "description": "Water level, depth LSD / USGS-340422107370801-40c9fdb920924c43b1afdc4f24ce54ea",
          "@iot.id": "40c9fdb920924c43b1afdc4f24ce54ea",
          "name": "40c9fdb920924c43b1afdc4f24ce54ea",
          "observationType": "Instantaneous",
          "observedArea": {
            "type": "Point",
            "coordinates": [
              -107.61885,
              34.07285
            ]
          },
          "phenomenonTime": "2021-08-15T19:00:00.000Z/2022-12-07T18:00:00.000Z",
          "properties": {
            "ParameterCode": "72019",
            "StatisticCode": "00011"
          },
          "resultTime": null,
          "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('40c9fdb920924c43b1afdc4f24ce54ea')",
          "unitOfMeasurement": {
            "name": "Feet",
            "symbol": "ft",
            "definition": ""
          }
        }
      ]
    },
    {
      "description": "Estuary",
      "@iot.id": "USGS-08077658",
      "Datastreams": [
        {
          "description": "Stream water level elevation above NGVD 1929, in feet / USGS-08077658-6460ad539ccf49328ac5d491305069a8",
          "@iot.id": "6460ad539ccf49328ac5d491305069a8",
          "name": "6460ad539ccf49328ac5d491305069a8",
          "observationType": "Instantaneous",
          "observedArea": {
            "type": "Point",
            "coordinates": [
              -94.9249228,
              29.3574568
            ]
          },
          "phenomenonTime": "2022-01-05T05:00:00.000Z/2023-02-03T20:00:00.000Z",
          "properties": {
            "ParameterCode": "63158",
            "StatisticCode": "00011"
          },
          "resultTime": null,
          "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('6460ad539ccf49328ac5d491305069a8')",
          "unitOfMeasurement": {
            "name": "Feet",
            "symbol": "ft",
            "definition": ""
          }
        },
        {
          "description": "Precipitation, total, inches / USGS-08077658-5547956e76a044deb5cd6e6aa8bdfa60",
          "@iot.id": "5547956e76a044deb5cd6e6aa8bdfa60",
          "name": "5547956e76a044deb5cd6e6aa8bdfa60",
          "observationType": "Instantaneous",
          "observedArea": {
            "type": "Point",
            "coordinates": [
              -94.9249228,
              29.3574568
            ]
          },
          "phenomenonTime": "2022-09-08T19:30:00.000Z/2023-02-03T20:00:00.000Z",
          "properties": {
            "ParameterCode": "00045"
          },
          "resultTime": null,
          "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('5547956e76a044deb5cd6e6aa8bdfa60')",
          "unitOfMeasurement": {
            "name": "in",
            "symbol": "in",
            "definition": ""
          }
        }
      ]
    }
  ]
}

More and Less Content

As a further step, if we only want an overview of the associated Datastreams; we’d like to reduce the content of the returned Datastreams to their identifier and description. This is done by adding the $select request parameter for the Datastreams within parentheses:

https://labs.waterdata.usgs.gov/sta/v1.1/Things?
	$select=@iot.id,description
	&$expand=Datastreams($select=@iot.id,description)
	&$top=1

The resulting response provides us with a simple overview of the Thing together with the available Datastreams pertaining to each Thing :

{
  "@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things?$top=1&$skip=1&$select=id,description&$expand=Datastreams%28%24select%3Did%2Cdescription%29",
  "value": [
    {
      "description": "Well",
      "@iot.id": "USGS-340422107370801",
      "Datastreams": [
        {
          "description": "Water level, depth LSD / USGS-340422107370801-40c9fdb920924c43b1afdc4f24ce54ea",
          "@iot.id": "40c9fdb920924c43b1afdc4f24ce54ea"
        }
      ]
    }
  ]
}

Conversely, the $expand parameter gives access to additional linked entities. Inside each $expand, all the request parameters can be used, including $expand itself. For example, we could request all the Datastreams for the Colorado at Lee’s Ferry, with the result and phenomenonTime of the latest Observation of each Datastream, and the total number of Observations.

https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')
	?$select=@iot.id,description
	&$expand=Datastreams(
		$select=@iot.id,description;
		$expand=Observations(
			$select=result,phenomenonTime;
			$orderby=phenomenonTime desc;
			$top=1;
			$count=true
		)
	)

Inside each expand, the request parameters are separated with a ; character, not with a &. The resulting response provides us with a simple overview of the single thing together with the available Datastreams pertaining to this Thing, and the last Observation for each Datastream:

{
  "description": "Stream",
  "@iot.id": "USGS-09380000",
  "Datastreams": [
    {
      "description": "None / USGS-09380000-0a10dcb7436f4af8a679a783ae3d8d58",
      "@iot.id": "0a10dcb7436f4af8a679a783ae3d8d58",
      "Observations@iot.count": 1144,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2022-07-20T19:00:00.000Z",
          "result": "824"
        }
      ]
    },
    {
      "description": "Specific cond at 25C / USGS-09380000-9d24cf50257a4f60b76b92e38f286cde",
      "@iot.id": "9d24cf50257a4f60b76b92e38f286cde",
      "Observations@iot.count": 56790,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-01-31T22:00:00.000Z",
          "result": "894"
        }
      ]
    },
    {
      "description": "Discharge / USGS-09380000-a62122d8ff094125b63bb2f73410b2b4",
      "@iot.id": "a62122d8ff094125b63bb2f73410b2b4",
      "Observations@iot.count": 68451,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-01-31T22:00:00.000Z",
          "result": "8280"
        }
      ]
    },
    {
      "description": "Temperature, water / USGS-09380000-b3c374548a8d4553868046dd9fda2582",
      "@iot.id": "b3c374548a8d4553868046dd9fda2582",
      "Observations@iot.count": 53851,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-01-31T22:00:00.000Z",
          "result": "8.1"
        }
      ]
    },
    {
      "description": "None / USGS-09380000-e1c4b44914ed43819cf8e2e2138e9064",
      "@iot.id": "e1c4b44914ed43819cf8e2e2138e9064",
      "Observations@iot.count": 35636,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-01-31T22:00:00.000Z",
          "result": "0.00"
        }
      ]
    },
    {
      "description": "None / USGS-09380000-c1d72c8390d144f78b51568a3755a5ad",
      "@iot.id": "c1d72c8390d144f78b51568a3755a5ad",
      "Observations@iot.count": 22649,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-01-31T22:00:00.000Z",
          "result": "8.16"
        }
      ]
    }
  ]
}

We now see serveral new things in the response:

  • Inside each Datastream there is a field Observations@iot.count the holds the total number of Observations for this Datastream.
  • Each Datastream has an Observations@iot.nextLink that holds a URL that points to the next Observation in the Datastream.

Select Distinct

Many of the properties assigned to entities are categorical. It is useful to generate a distinct list of those properties, which is what the Select Distinct extension to the SensorThings standard provides.

For example, here are all the different mainstems that are tied to locations in the USGS SensorThings Implementation

https://labs.waterdata.usgs.gov/sta/v1.1/Locations?
	$select=distinct:properties/mainstemURL,properties/mainstemNameAtOutlet,properties/mainstemNameAtOutletGNIS
	&$orderby=properties/mainstemURL

In addition, it is possible to combine this with other Odata operators, such as substringof such that all the different mainstems that have “salmon” in the name can be found , including 4 different Salmon Rivers!

https://labs.waterdata.usgs.gov/sta/v1.1/Locations?
	$filter=substringof(tolower('colorado'), tolower(properties/mainstemNameAtOutlet))
	&$select=distinct:properties/mainstemURL,properties/mainstemNameAtOutlet,properties/mainstemNameAtOutletGNIS
	&$orderby=properties/mainstemURL

Response Formats

DataArray

The SensorThings standard includes the Data Array Extension . DataArray result format can format Observations in a more compact/efficient way by stripping out the JSON keys and instead returning those keys at the top of the response. It only works on collections of Observations.

https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('2463374192ca43468cad14834898f975')/Observations?
	$orderby=phenomenonTime asc&$filter=phenomenonTime gt now() sub duration'P1D'
	&$resultFormat=DataArray
	&$top=2 


{
  "@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('2463374192ca43468cad14834898f975')/Observations?$top=2&$skip=2&$filter=%28phenomenonTime+gt+%28now%28%29+sub+duration%27P1D%27%29%29&$resultFormat=DataArray&$orderby=phenomenonTime+asc",
  "value": [
    {
      "Datastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('2463374192ca43468cad14834898f975')",
      "components": [
        "id",
        "phenomenonTime",
        "result",
        "resultTime",
        "resultQuality",
        "validTime",
        "parameters"
      ],
      "dataArray@iot.count": 2,
      "dataArray": [
        [
          "2463374192ca43468cad14834898f9751672769700",
          "2023-01-03T18:15:00.000Z",
          "3527.2",
          null,
          [
            {
              "DQ_Result": {
                "label": "Working"
              },
              "nameOfMeasure": "DQ_Status"
            }
          ],
          null,
          {
            "site": "USGS-09379900"
          }
        ],
        [
          "2463374192ca43468cad14834898f9751672770600",
          "2023-01-03T18:30:00.000Z",
          "3527.3",
          null,
          [
            {
              "DQ_Result": {
                "label": "Working"
              },
              "nameOfMeasure": "DQ_Status"
            }
          ],
          null,
          {
            "site": "USGS-09379900"
          }
        ]
      ]
    }
  ]
}

geoJSON

The geoJSON result format changes the response of the server to be geoJSON that is amenable to displaying on a web map. This returns all the Things within a bounding box (what we use on the monitoring location page maps). Note that locations need to be pulled in addition to Thing to fully build out the geoJSON structure.


https://labs.waterdata.usgs.gov/sta/v1.1/Things?
	$expand=Locations($select=id,location)
	&$filter=st_within(Locations/location, geography'Polygon((-112 37.0,-112 36.8,-111 36.8,-111 37.0,-112 37.0))')
	&$resultFormat=GeoJSON&
	$top=1000 


{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": "USGS-09379900",
        "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09379900')",
        "name": "USGS-09379900",
        "description": "Lake",
        "properties/state": "Arizona",
        "properties/active": true,
        "properties/agency": "U.S. Geological Survey",
        "properties/county": "Coconino County",
        "properties/country": "US",
        "properties/district": "Arizona",
        "properties/stateFIPS": "US:04",
        "properties/agencyCode": "USGS",
        "properties/countyFIPS": "US:04:005",
        "properties/countryFIPS": "US",
        "properties/districtCode": "49",
        "properties/altitudeDatum": "National Geodetic Vertical Datum of 1929",
        "properties/altitudeMethod": "Level or other surveyed method.",
        "properties/hydrologicUnit": "140700061105",
        "properties/altitudeAccuracy": "0.1",
        "properties/monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/09379900",
        "properties/monitoringLocationName": "LAKE POWELL AT GLEN CANYON DAM, AZ",
        "properties/monitoringLocationType": "Lake",
        "properties/monitoringLocationNumber": "09379900",
        "properties/monitoringLocationAltitudeLandSurface": "3718.82",
        "Locations/0/id": "a2184b84-2d28-11ec-9852-7f9b96b407a9"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -111.4840472,
          36.9366548
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": "USGS-09380000",
        "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')",
        "name": "USGS-09380000",
        "description": "Stream",
        "properties/state": "Arizona",
        "properties/active": true,
        "properties/agency": "U.S. Geological Survey",
        "properties/county": "Coconino County",
        "properties/country": "US",
        "properties/district": "Arizona",
        "properties/stateFIPS": "US:04",
        "properties/agencyCode": "USGS",
        "properties/countyFIPS": "US:04:005",
        "properties/countryFIPS": "US",
        "properties/districtCode": "04",
        "properties/altitudeDatum": "North American Vertical Datum of 1988",
        "properties/altitudeMethod": "Interpolated from Digital Elevation Model",
        "properties/hydrologicUnit": "140700061105",
        "properties/altitudeAccuracy": "4.3",
        "properties/monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/09380000",
        "properties/monitoringLocationName": "COLORADO RIVER AT LEES FERRY, AZ",
        "properties/monitoringLocationType": "Stream",
        "properties/monitoringLocationNumber": "09380000",
        "properties/monitoringLocationAltitudeLandSurface": "3083",
        "Locations/0/id": "8abb4836-2d2a-11ec-84b5-f373f8c9b79c"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": "USGS-09382000",
        "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09382000')",
        "name": "USGS-09382000",
        "description": "Stream",
        "properties/state": "Arizona",
        "properties/active": true,
        "properties/agency": "U.S. Geological Survey",
        "properties/county": "Coconino County",
        "properties/country": "US",
        "properties/district": "Arizona",
        "properties/stateFIPS": "US:04",
        "properties/agencyCode": "USGS",
        "properties/countyFIPS": "US:04:005",
        "properties/countryFIPS": "US",
        "properties/districtCode": "04",
        "properties/altitudeDatum": "National Geodetic Vertical Datum of 1929",
        "properties/altitudeMethod": "Unknown.",
        "properties/hydrologicUnit": "140700070706",
        "properties/altitudeAccuracy": "5",
        "properties/monitoringLocationUrl": "https://waterdata.usgs.gov/monitoring-location/09382000",
        "properties/monitoringLocationName": "PARIA RIVER AT LEES FERRY, AZ",
        "properties/monitoringLocationType": "Stream",
        "properties/monitoringLocationNumber": "09382000",
        "properties/monitoringLocationAltitudeLandSurface": "3123.68",
        "Locations/0/id": "8d62e364-2d2a-11ec-84b5-bbdffdca97a5"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -111.5946052,
          36.8722097
        ]
      }
    }
  ]
}
And here is the same query ALSO including the latest value for each datastream:

https://labs.waterdata.usgs.gov/sta/v1.1/Things?
	$expand=Locations($select=id,location),
  Datastreams($select=ObservedProperty/Observations($select=phenomenonTime,result;$top=1;$orderBy=phenomenonTime desc)
	&$filter=st_within(Locations/location,geography'Polygon((-112 37.0,-112 36.8,-111 36.8,-111 37.0,-112 37.0))%27)
	&$resultFormat=GeoJSON&$top=1000

CSV

The CSV result format changes the response of the server into CSV that conforms with rfc4180 . As mapping a deeply nested JSON data structure to a flat format such as CSV can be quite complex, a number of compromises have had to be made. The details can be found at the FROST-Server Documentation Site .

The following example returns well water monitoring information from a location in New Mexico, as CSV:

https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('2463374192ca43468cad14834898f975')/Observations
	?$select=result,phenomenonTime,parameters
	&$expand=Datastream($select=id,name)
	&$orderby=phenomenonTime asc
	&$resultFormat=CSV

Filters and Counts

Filtering

In many use cases, the response should only contain objects that pertain to some specific criteria. The $filter request parameter makes it possible to filter the data based on the values of specific attributes of the requested data. Thus, one could request all values above a certain threshold or measured between two specific points in time. The following request returns all Observations where the temperature result value is greater than 5.1 degrees C:

https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('15dc337abc2c47219c2f29459baa7b66')/Observations?
	$orderby=phenomenonTime asc
	&$filter=result gt '5.1'&$top=5

This request provides the following response:

{
  "@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('15dc337abc2c47219c2f29459baa7b66')/Observations?$top=5&$skip=5&$filter=%28result+gt+%275.1%27%29&$orderby=phenomenonTime+asc",
  "value": [
    {
      "@iot.id": "303adee2-d880-11ec-a9dd-c72614e3b737",
      "phenomenonTime": "2022-01-24T21:45:00.000Z",
      "parameters": {
        "site": "USGS-07144100"
      },
      "result": "5.2",
      "resultTime": null,
      "resultQuality": [
        {
          "DQ_Result": {
            "label": "Working"
          },
          "nameOfMeasure": "DQ_Status"
        }
      ],
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303adee2-d880-11ec-a9dd-c72614e3b737')",
      "Datastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303adee2-d880-11ec-a9dd-c72614e3b737')/Datastream",
      "FeatureOfInterest@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303adee2-d880-11ec-a9dd-c72614e3b737')/FeatureOfInterest",
      "MultiDatastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303adee2-d880-11ec-a9dd-c72614e3b737')/MultiDatastream"
    },
    {
      "@iot.id": "303b4990-d880-11ec-a9dd-8f747a07a1ad",
      "phenomenonTime": "2022-01-24T22:00:00.000Z",
      "parameters": {
        "site": "USGS-07144100"
      },
      "result": "5.3",
      "resultTime": null,
      "resultQuality": [
        {
          "DQ_Result": {
            "label": "Working"
          },
          "nameOfMeasure": "DQ_Status"
        }
      ],
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303b4990-d880-11ec-a9dd-8f747a07a1ad')",
      "Datastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303b4990-d880-11ec-a9dd-8f747a07a1ad')/Datastream",
      "FeatureOfInterest@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303b4990-d880-11ec-a9dd-8f747a07a1ad')/FeatureOfInterest",
      "MultiDatastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303b4990-d880-11ec-a9dd-8f747a07a1ad')/MultiDatastream"
    },
    {
      "@iot.id": "303bb2fe-d880-11ec-a9dd-c7ea6f128bc6",
      "phenomenonTime": "2022-01-24T22:15:00.000Z",
      "parameters": {
        "site": "USGS-07144100"
      },
      "result": "5.3",
      "resultTime": null,
      "resultQuality": [
        {
          "DQ_Result": {
            "label": "Working"
          },
          "nameOfMeasure": "DQ_Status"
        }
      ],
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303bb2fe-d880-11ec-a9dd-c7ea6f128bc6')",
      "Datastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303bb2fe-d880-11ec-a9dd-c7ea6f128bc6')/Datastream",
      "FeatureOfInterest@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303bb2fe-d880-11ec-a9dd-c7ea6f128bc6')/FeatureOfInterest",
      "MultiDatastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303bb2fe-d880-11ec-a9dd-c7ea6f128bc6')/MultiDatastream"
    },
    {
      "@iot.id": "303c4200-d880-11ec-a9dd-ef84f11b491f",
      "phenomenonTime": "2022-01-24T22:30:00.000Z",
      "parameters": {
        "site": "USGS-07144100"
      },
      "result": "5.4",
      "resultTime": null,
      "resultQuality": [
        {
          "DQ_Result": {
            "label": "Working"
          },
          "nameOfMeasure": "DQ_Status"
        }
      ],
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303c4200-d880-11ec-a9dd-ef84f11b491f')",
      "Datastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303c4200-d880-11ec-a9dd-ef84f11b491f')/Datastream",
      "FeatureOfInterest@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303c4200-d880-11ec-a9dd-ef84f11b491f')/FeatureOfInterest",
      "MultiDatastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303c4200-d880-11ec-a9dd-ef84f11b491f')/MultiDatastream"
    },
    {
      "@iot.id": "303cb654-d880-11ec-a9dd-c7436a016e24",
      "phenomenonTime": "2022-01-24T22:45:00.000Z",
      "parameters": {
        "site": "USGS-07144100"
      },
      "result": "5.4",
      "resultTime": null,
      "resultQuality": [
        {
          "DQ_Result": {
            "label": "Working"
          },
          "nameOfMeasure": "DQ_Status"
        }
      ],
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303cb654-d880-11ec-a9dd-c7436a016e24')",
      "Datastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303cb654-d880-11ec-a9dd-c7436a016e24')/Datastream",
      "FeatureOfInterest@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303cb654-d880-11ec-a9dd-c7436a016e24')/FeatureOfInterest",
      "MultiDatastream@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Observations('303cb654-d880-11ec-a9dd-c7436a016e24')/MultiDatastream"
    }
  ]
}

There are extensive additonal filter options in SensorThings that allow for nearly unlimited flexibility in crafting a query. The following links are to specific components of the Frost Server documentation site .

Counts

Given the amount of data used for counts, it is recommended to limit the use of counts for effective and to narrow down the critera for best results.

In many use cases, it is important to know how many objects of a specific type are available from the API. While many default deployments do not automatically return this value, setting the request parameter $count to true enables this functionality. When $count=true is appended to the request URL, the response will contain an @iot.count attribute providing the total number of objects available from the API data source. A closely related request parameter is top, that makes it possible to specify the maximum number of objects to be returned in the response. Adding $top=4 to the request URL will provide a maximum of 4 objects in the response. The following URL specifies that the most recent one be returned, together with the total number of Observations available for each datastream

https://labs.waterdata.usgs.gov/sta/v1.1/Things('USGS-09380000')/Datastreams?
	$expand=Observations(
		$select=result,phenomenonTime;$orderby=phenomenonTime desc;$top=1;$count=true
		)

This request provides the following response:

{
  "value": [
    {
      "description": "Discharge / USGS-09380000-a62122d8ff094125b63bb2f73410b2b4",
      "@iot.id": "a62122d8ff094125b63bb2f73410b2b4",
      "name": "a62122d8ff094125b63bb2f73410b2b4",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2021-09-16T11:00:00.000Z/2023-02-21T17:00:00.000Z",
      "properties": {
        "ParameterCode": "00060",
        "StatisticCode": "00011"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')",
      "unitOfMeasurement": {
        "name": "Cubic Feet per Second",
        "symbol": "ft^3/s",
        "definition": ""
      },
      "Observations@iot.count": 70447,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-02-21T17:00:00.000Z",
          "result": "9170"
        }
      ],
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/ObservedProperty",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/Sensor",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/Thing",
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('a62122d8ff094125b63bb2f73410b2b4')/Observations"
    },
    {
      "description": "None / USGS-09380000-0a10dcb7436f4af8a679a783ae3d8d58",
      "@iot.id": "0a10dcb7436f4af8a679a783ae3d8d58",
      "name": "0a10dcb7436f4af8a679a783ae3d8d58",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2022-07-08T20:30:00.000Z/2022-07-20T19:00:00.000Z",
      "properties": {
        "ParameterCode": "00095",
        "StatisticCode": "00011",
        "WebDescription": "Starts 7/8/22"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')",
      "unitOfMeasurement": {
        "name": "uS/cm",
        "symbol": "uS/cm",
        "definition": ""
      },
      "Observations@iot.count": 1144,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2022-07-20T19:00:00.000Z",
          "result": "824"
        }
      ],
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/ObservedProperty",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/Sensor",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/Thing",
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('0a10dcb7436f4af8a679a783ae3d8d58')/Observations"
    },
    {
      "description": "Temperature, water / USGS-09380000-b3c374548a8d4553868046dd9fda2582",
      "@iot.id": "b3c374548a8d4553868046dd9fda2582",
      "name": "b3c374548a8d4553868046dd9fda2582",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2021-07-12T20:30:00.000Z/2023-02-21T18:00:00.000Z",
      "properties": {
        "ParameterCode": "00010",
        "StatisticCode": "00011"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')",
      "unitOfMeasurement": {
        "name": "Degrees Centigrade",
        "symbol": "degC",
        "definition": ""
      },
      "Observations@iot.count": 55848,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-02-21T18:00:00.000Z",
          "result": "7.7"
        }
      ],
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/ObservedProperty",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/Sensor",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/Thing",
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('b3c374548a8d4553868046dd9fda2582')/Observations"
    },
    {
      "description": "Specific cond at 25C / USGS-09380000-9d24cf50257a4f60b76b92e38f286cde",
      "@iot.id": "9d24cf50257a4f60b76b92e38f286cde",
      "name": "9d24cf50257a4f60b76b92e38f286cde",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2021-07-12T18:45:00.000Z/2023-02-21T18:00:00.000Z",
      "properties": {
        "Thresholds": [
          {
            "Name": "HIGH SC THRESHOLD",
            "Type": "ThresholdAbove",
            "Periods": [
              {
                "EndTime": "9999-12-31T23:59:59.9999999+00:00",
                "StartTime": "2018-01-10T01:00:00.0000000-07:00",
                "SuppressData": true,
                "ReferenceValue": 1200
              }
            ],
            "ReferenceCode": "Operational limit - high-Public"
          },
          {
            "Name": "LOW SC THRESHOLD",
            "Type": "ThresholdBelow",
            "Periods": [
              {
                "EndTime": "9999-12-31T23:59:59.9999999+00:00",
                "StartTime": "2018-01-10T01:00:00.0000000-07:00",
                "SuppressData": true,
                "ReferenceValue": 400
              }
            ],
            "ReferenceCode": "Operational limit - low-Public"
          }
        ],
        "ParameterCode": "00095",
        "StatisticCode": "00011"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')",
      "unitOfMeasurement": {
        "name": "uS/cm",
        "symbol": "uS/cm",
        "definition": ""
      },
      "Observations@iot.count": 58787,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-02-21T18:00:00.000Z",
          "result": "911"
        }
      ],
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/ObservedProperty",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/Sensor",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/Thing",
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('9d24cf50257a4f60b76b92e38f286cde')/Observations"
    },
    {
      "description": "None / USGS-09380000-c1d72c8390d144f78b51568a3755a5ad",
      "@iot.id": "c1d72c8390d144f78b51568a3755a5ad",
      "name": "c1d72c8390d144f78b51568a3755a5ad",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2022-07-08T18:30:00.000Z/2023-02-21T18:00:00.000Z",
      "properties": {
        "ParameterCode": "00065",
        "StatisticCode": "00011",
        "WebDescription": "PRIMARY STAGE"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')",
      "unitOfMeasurement": {
        "name": "Feet",
        "symbol": "ft",
        "definition": ""
      },
      "Observations@iot.count": 24649,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-02-21T18:00:00.000Z",
          "result": "8.50"
        }
      ],
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/ObservedProperty",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/Sensor",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/Thing",
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('c1d72c8390d144f78b51568a3755a5ad')/Observations"
    },
    {
      "description": "None / USGS-09380000-e1c4b44914ed43819cf8e2e2138e9064",
      "@iot.id": "e1c4b44914ed43819cf8e2e2138e9064",
      "name": "e1c4b44914ed43819cf8e2e2138e9064",
      "observationType": "Instantaneous",
      "observedArea": {
        "type": "Point",
        "coordinates": [
          -111.5878722,
          36.8643333
        ]
      },
      "phenomenonTime": "2022-01-10T01:30:00.000Z/2023-02-21T18:00:00.000Z",
      "properties": {
        "ParameterCode": "00045"
      },
      "resultTime": null,
      "@iot.selfLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')",
      "unitOfMeasurement": {
        "name": "in",
        "symbol": "in",
        "definition": ""
      },
      "Observations@iot.count": 37636,
      "Observations@iot.nextLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/Observations?$top=1&$skip=1&$select=result,phenomenonTime&$orderby=phenomenonTime+desc&$count=true",
      "Observations": [
        {
          "phenomenonTime": "2023-02-21T18:00:00.000Z",
          "result": "0.00"
        }
      ],
      "ObservedProperty@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/ObservedProperty",
      "Sensor@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/Sensor",
      "Thing@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/Thing",
      "Observations@iot.navigationLink": "https://labs.waterdata.usgs.gov/sta/v1.1/Datastreams('e1c4b44914ed43819cf8e2e2138e9064')/Observations"
    }
  ]
}
Based on this response, we can see that four of the sixteen available Observations have been returned. The $count parameter can also be used inside an $expand parameter, for instance, to request the number of Datastreams in a Thing.

References

What is OData ?

The Open Data Protocol (OData) is a data access protocol built on core protocols like HTTP and commonly accepted methodologies like REST for the web. There are various kinds of libraries and tools can be used to consume OData services.

Learn more about this protocol in this tutorial: https://www.odata.org/getting-started/basic-tutorial/ .

Additional Resources