Difference between revisions of "V2 API"

From floodzilla-wiki
Jump to navigation Jump to search
(Created page with "== Overview == These notes apply to all Floodzilla services. All object payloads are in JSON format. All date/time fields are in UTC. === General Client API === ==== GetRe...")
 
 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
== Overview ==
+
==Overview==
 
These notes apply to all Floodzilla services.
 
These notes apply to all Floodzilla services.
  
Line 6: Line 6:
 
All date/time fields are in UTC.
 
All date/time fields are in UTC.
  
−
=== General Client API ===
+
==General Client API==
  
−
==== GetRegion ====
+
===GetRegion===
  
 
Returns all of the necessary information about a region.  The client should hardcode (or, eventually, allow choosing from a list, maybe?) a region id.  Currently available region IDs:
 
Returns all of the necessary information about a region.  The client should hardcode (or, eventually, allow choosing from a list, maybe?) a region id.  Currently available region IDs:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
| Region 1|| The main SVPA region.  Should always be used in production mode.
+
|Region 1||The main SVPA region.  Should always be used in production mode.
 
|-
 
|-
−
| Region 17 || A Testing region.  There's nothing there, yet, but hopefully it will have testing data eventually.
+
|Region 17||A Testing region.  There's nothing there, yet, but hopefully it will have testing data eventually.
 
|}
 
|}
  
−
Endpoint: GET /api/v2/GetRegion?regionId=<region>
+
'''Caching''':
 +
This is expected to change VERY rarely.  Fetch once at app startup and cache forever.
 +
 
 +
'''Endpoint''': <code>GET /api/v2/GetRegion?regionId=<region></code>
 +
 
 +
'''Example return value''':
 +
<pre>{
 +
  "id": 1,
 +
  "name": "Snoqualmie Valley",
 +
  "timezone": "America/Los_Angeles",
 +
  "baseUrl": "https://floodzilla.com",
 +
  "defaultForecastGaugeList": [
 +
    "USGS-SF17/USGS-NF10/USGS-MF11",
 +
    "USGS-38",
 +
    "USGS-22"
 +
  ]
 +
}</pre>
 +
 
 +
'''Notes''':
 +
 
 +
*Internally, all times are represented as UTC.  Whenever a client displays a time/date, it must be converted to "Region Time" using the region timezone.
 +
 
 +
===GetMetagauges===
 +
 
 +
Returns all of the metagauges for a region.  Currently there is only one metagauge in the whole world, and it is in region 1.
 +
 
 +
'''Caching''':
 +
This can change if we change the flood level labels.  Fetch once per day.
 +
 
 +
'''Endpoint''': <code>GET /api/v2/GetMetagauges?regionId=<region></code>
 +
 
 +
'''Example return value''':
 +
<pre>[
 +
  {
 +
    "ids": "USGS-SF17/USGS-NF10/USGS-MF11",
 +
    "siteIds": "GARW1-SNQW1-TANW1",
 +
    "name": "Sum of the 3 forks",
 +
    "shortName": "Forks",
 +
    "stageOne": 10000,
 +
    "stageTwo": 12000
 +
  }
 +
]</pre>
 +
 
 +
'''Notes''':
 +
 
 +
* "Stage One" and "Stage Two" are the flood warning and flooding levels, respectively.
 +
 
 +
===GetForecast===
 +
 
 +
Returns a forecast for the specified set of gauges.
 +
 
 +
'''Caching''':
 +
 
 +
New forecasts are published every couple of hours during flood events, and daily? during dry times.  The back end checks for new forecasts every 5 minutes.
 +
 
 +
'''Endpoint''': <code>GET /api/v2/GetForecast?regionId=[region]&gaugeIds=[gaugeList]&ifNewerThan=[utcTime]</code>
 +
 
 +
'''Example Request''': <code>GET /api/v2/GetForecast?regionId=1&ifNewerThan=2023-03-27T15:49:00Z&gaugeIds=USGS-SF17/USGS-NF10/USGS-MF11,USGS-38,USGS-22</code>
 +
 
 +
'''Example return value''':
 +
<pre>{
 +
    "USGS-SF17/USGS-NF10/USGS-MF11": {
 +
        "noaaSiteId": "",
 +
        "forecastCreated": "2023-03-27T15:49:00Z",
 +
        "forecastId": 0,
 +
        "peaks": {
 +
            "timestamps": [
 +
                "2023-03-28T12:00:00Z",
 +
                ...],
 +
            "waterHeights": [
 +
                4.38,
 +
                ...],
 +
            "discharges": [
 +
                1345.0,
 +
                ...]
 +
        },
 +
        "timestamps": [
 +
            "2023-03-27T18:00:00Z",
 +
            ...],
 +
        "waterHeights": [
 +
            4.38,
 +
            ...],
 +
        "discharges": [
 +
            1349.0,
 +
            ...]
 +
        },
 +
    "USGS-38": null,
 +
}</pre>
 +
 
 +
'''Notes''':
 +
 
 +
Returns 'null' for a gauge if the latest forecast is not newer than the specified time.
 +
 
 +
===GetRecentReadings===
 +
 
 +
Returns recent readings for a specified set of gauges.
 +
 
 +
'''Caching''':
 +
 
 +
Although new readings generally come in on 5- or 15-minute intervals, there's no guarantee that they'll be perfectly aligned with clock time.  We should check for new
 +
readings at least once per minute.
 +
 
 +
'''Endpoint''': <code>GET /api/v2/GetRecentReadings?regionId=[region]&gaugeIds=[gaugeList]&minutes=[5760]&prevMaxReadingId=[id]</code>
 +
 
 +
'''Example Request''': <code>GET /api/v2/GetRecentReadings?regionId=1&gaugeIds=USGS-SF17/USGS-NF10/USGS-MF11,USGS-38,USGS-22&minutes=5760&prevMaxReadingId=0
 +
 
 +
'''Example return value''':
 +
<pre>{
 +
    "maxReadingId": 2046456.
 +
    "readings": {
 +
        "USGS-22": {
 +
            "trendCfsPerHour": 0.0,
 +
            "trendFeetPerHour": 0.0,
 +
            "readingIds": [
 +
                2046431,
 +
                ...
 +
            ],
 +
            "timestamps": [
 +
                "2023-04-03T17:15:00Z",
 +
                ...
 +
            ],
 +
            "waterHeights": [
 +
                46.04,
 +
                ...
 +
            ],
 +
            "discharges": [
 +
                2000.0,
 +
                ...
 +
            ]
 +
        }
 +
    }
 +
}</pre>
 +
 
 +
'''Notes''':
 +
 
 +
If there are no readings for a given gauge with an ID greater than prevMaxReadingId, it will not appear in the response.  If a gauge has no reading IDs or water height values (e.g. it's a metagauge), those arrays will be missing.

Latest revision as of 18:02, 3 April 2023

Overview

These notes apply to all Floodzilla services.

All object payloads are in JSON format.

All date/time fields are in UTC.

General Client API

GetRegion

Returns all of the necessary information about a region. The client should hardcode (or, eventually, allow choosing from a list, maybe?) a region id. Currently available region IDs:

Region 1 The main SVPA region. Should always be used in production mode.
Region 17 A Testing region. There's nothing there, yet, but hopefully it will have testing data eventually.

Caching: This is expected to change VERY rarely. Fetch once at app startup and cache forever.

Endpoint: GET /api/v2/GetRegion?regionId=<region>

Example return value: 

{
  "id": 1,
  "name": "Snoqualmie Valley",
  "timezone": "America/Los_Angeles",
  "baseUrl": "https://floodzilla.com",
  "defaultForecastGaugeList": [
    "USGS-SF17/USGS-NF10/USGS-MF11",
    "USGS-38",
    "USGS-22"
  ]
}

Notes:

  • Internally, all times are represented as UTC. Whenever a client displays a time/date, it must be converted to "Region Time" using the region timezone.

GetMetagauges

Returns all of the metagauges for a region. Currently there is only one metagauge in the whole world, and it is in region 1.

Caching: This can change if we change the flood level labels. Fetch once per day.

Endpoint: GET /api/v2/GetMetagauges?regionId=<region>

Example return value: 

[
  {
    "ids": "USGS-SF17/USGS-NF10/USGS-MF11",
    "siteIds": "GARW1-SNQW1-TANW1",
    "name": "Sum of the 3 forks",
    "shortName": "Forks",
    "stageOne": 10000,
    "stageTwo": 12000
  }
]

Notes:

  • "Stage One" and "Stage Two" are the flood warning and flooding levels, respectively.

GetForecast

Returns a forecast for the specified set of gauges.

Caching:

New forecasts are published every couple of hours during flood events, and daily? during dry times. The back end checks for new forecasts every 5 minutes.

Endpoint: GET /api/v2/GetForecast?regionId=[region]&gaugeIds=[gaugeList]&ifNewerThan=[utcTime]

Example Request: GET /api/v2/GetForecast?regionId=1&ifNewerThan=2023-03-27T15:49:00Z&gaugeIds=USGS-SF17/USGS-NF10/USGS-MF11,USGS-38,USGS-22

Example return value: 

{
    "USGS-SF17/USGS-NF10/USGS-MF11": {
        "noaaSiteId": "",
        "forecastCreated": "2023-03-27T15:49:00Z",
        "forecastId": 0,
        "peaks": {
            "timestamps": [
                "2023-03-28T12:00:00Z",
                ...],
            "waterHeights": [
                4.38,
                ...],
            "discharges": [
                1345.0,
                ...]
        },
        "timestamps": [
            "2023-03-27T18:00:00Z",
            ...],
        "waterHeights": [
            4.38,
            ...],
        "discharges": [
            1349.0,
            ...]
        },
    "USGS-38": null,
}

Notes:

Returns 'null' for a gauge if the latest forecast is not newer than the specified time.

GetRecentReadings

Returns recent readings for a specified set of gauges.

Caching:

Although new readings generally come in on 5- or 15-minute intervals, there's no guarantee that they'll be perfectly aligned with clock time. We should check for new readings at least once per minute.

Endpoint: GET /api/v2/GetRecentReadings?regionId=[region]&gaugeIds=[gaugeList]&minutes=[5760]&prevMaxReadingId=[id]

Example Request: GET /api/v2/GetRecentReadings?regionId=1&gaugeIds=USGS-SF17/USGS-NF10/USGS-MF11,USGS-38,USGS-22&minutes=5760&prevMaxReadingId=0

Example return value: 

{
    "maxReadingId": 2046456.
    "readings": {
        "USGS-22": {
            "trendCfsPerHour": 0.0,
            "trendFeetPerHour": 0.0,
            "readingIds": [
                2046431,
                ...
            ],
            "timestamps": [
                "2023-04-03T17:15:00Z",
                ...
            ],
            "waterHeights": [
                46.04,
                ...
            ],
            "discharges": [
                2000.0,
                ...
            ]
        }
    }
}

Notes:

If there are no readings for a given gauge with an ID greater than prevMaxReadingId, it will not appear in the response. If a gauge has no reading IDs or water height values (e.g. it's a metagauge), those arrays will be missing.

Retrieved from "http://wiki.floodzilla.com/index.php?title=V2_API&oldid=583"