Querying Data

We measure and record all kinds of sensor data but the Phenomena is actually the primary unit in the Sensorcast universe, so we really measure and record phenomena. All the data in the system (except account data) is accessible via the API. For the moment we will focus on querying phenomena. The remainder of the API, and other details are documented in the Wiki (or will be).

To query the phenomena you need to POST a JSON document that specifies the parameters of the data you want to select.  For example, create a file called example-request.json (change the dates to be  recent) with the following:

{
    "startTime": "2016-09-19T00:00:00-0700",
    "endTime": "2016-09-19T23:59:59-0700",

    "area": {
        "square": {
            "minLatLon": "32.72798,-119.53618",
            "maxLatLon": "34.67010,-116.02055"
        }
    },
    "filters": [
        "latest"
     ],
     "format": "json"
}

The startTime and endTime specify the period you want to search. The square specifies an area bounded by minimum and maximum latitude and longitude. You can change these, and the time, to suit your location and preference.

Then you can use the following to download the data:

curl -v -L --post302 -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d @example-request.json  \
     https://api.sensorcast.org/v1/phenomena \
     >example-response.json

You will get a JSON document back that contains the latest recorded phenomena for the parameters you specified.  (NOTE: The data returned will not be human readable unless you pretty-print it.  A pretty-print version of the data returned from the request above can be found here.)

A snippet of the data returned is below:

{
     "phenomena": [
     {
         "acquisitionDuration": 60005,
         "acquisitionPeriod": 0,
         "acquisitionTime": "2016/09/19 07:01:10 UTC",
         "altitude": -18.0,
         "created": "2016/09/19 08:52:37 UTC",
         "dimension": "environment.magnetic-field-average",
         "id": 385013544,
         "latitude": 33.70623774,
         "longitude": -117.78298289,
         "metadata": 305546333,
         "modified": "2016/09/19 08:52:37 UTC",
         "quantity": "41.53",
         "sensorId": "00000000-770d-59af-ffff-ffffa76463ee",
         "stationId": "Sensorcast-Android-1.0",
         "units": "uT"
     },
     {
         "acquisitionDuration": 0,
         "acquisitionPeriod": 0,
         "acquisitionTime": "2016/09/19 07:46:08 UTC",
         "altitude": -9.23,
         "created": "2016/09/19 07:50:26 UTC",
         "dimension": "seismic",
         "id": 384930795,
         "latitude": 34.0088333,
         "longitude": -116.9038333,
         "metadata": 305532717,
         "modified": "2016/09/19 07:50:26 UTC",
         "quantity": "0.52",
         "sensorId": "ci",
         "stationId": "USGS-Seismic",
         "units": "Ml"
     },
     {
         "acquisitionDuration": 0,
         "acquisitionPeriod": 0,
         "acquisitionTime": "2016/09/20 00:53:00 UTC",
         "altitude": 0.0,
         "created": "2016/09/20 01:16:30 UTC",
         "dimension": "weather.air-temperature",
         "id": 386345069,
         "latitude": 33.68,
         "longitude": -117.86639,
         "metadata": 305764284,
         "modified": "2016/09/20 01:16:30 UTC",
         "quantity": "25.60",
         "sensorId": "KSNA",
         "stationId": "NOAA.NWS.METAR.KSNA",
         "units": "C"
     },
     ....
     ....
     ....