V2 API - Revision history

DaveSanderman at 18:02, 3 April 2023

2023-04-03T18:02:02Z

2023-04-03T18:00:37Z

2023-03-28T16:46:42Z

2023-03-27T18:13:52Z

2023-03-27T18:07:32Z

2023-03-27T18:07:07Z

GetMetagages

2023-03-20T18:54:48Z

2023-03-20T18:31:18Z

2023-03-20T18:30:49Z

2023-03-20T18:30:00Z

Overview

@@ Line 117: / Line 117: @@
 '''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.
+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
 '''Endpoint''': <code>GET /api/v2/GetRecentReadings?regionId=[region]&gaugeIds=[gaugeList]&minutes=[5760]&prevMaxReadingId=[id]</code>

@@ Line 73: / Line 73: @@
 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=[gageList]&ifNewerThan=[utcTime]</code>
+'''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>
@@ Line 109: / Line 109: @@
 '''Notes''':
-Returns 'null' for a gage if the latest forecast is not newer than the specified time.
+Returns 'null' for a gauge if the latest forecast is not newer than the specified time.

@@ Line 83: / Line 83: @@
          "forecastCreated": "2023-03-27T15:49:00Z",
          "forecastId": 0,
          "timestamps": [
              "2023-03-27T18:00:00Z",

← Older revision		Revision as of 18:13, 27 March 2023
Line 64:		Line 64:

	* "Stage One" and "Stage Two" are the flood warning and flooding levels, respectively.		* "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=[gageList]&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,
		+	"timestamps": [
		+	"2023-03-27T18:00:00Z",
		+	...],
		+	"waterHeights": [
		+	4.38,
		+	...],
		+	"discharges": [
		+	1349.0,
		+	...]
		+	},
		+	"USGS-38": null,
		+	}</pre>
		+
		+	'''Notes''':
		+
		+	Returns 'null' for a gage if the latest forecast is not newer than the specified time.

@@ Line 29: / Line 29: @@
    "timezone": "America/Los_Angeles",
    "baseUrl": "https://floodzilla.com",
-   "defaultForecastGageList": [
+   "defaultForecastGaugeList": [
      "USGS-SF17/USGS-NF10/USGS-MF11",
      "USGS-38",

@@ Line 40: / Line 40: @@
 *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.
-===GetMetagages===
+===GetMetagauges===
-Returns all of the metagages for a region.  Currently there is only one metagage in the whole world, and it is in region 1.
+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/GetMetagages?regionId=<region></code>
+'''Endpoint''': <code>GET /api/v2/GetMetagauges?regionId=<region></code>
 '''Example return value''':

← Older revision		Revision as of 18:54, 20 March 2023
Line 39:		Line 39:

	*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.		*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.
		+
		+	===GetMetagages===
		+
		+	Returns all of the metagages for a region. Currently there is only one metagage 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/GetMetagages?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.

@@ Line 6: / Line 6: @@
 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:

@@ Line 17: / Line 17: @@
 |Region 17||A Testing region.  There's nothing there, yet, but hopefully it will have testing data eventually.
 |}
 '''Endpoint''': <code>GET /api/v2/GetRegion?regionId=<region></code>

@@ Line 18: / Line 18: @@
 |}
-Endpoint: <code>GET /api/v2/GetRegion?regionId=<region></code>
+'''Endpoint''': <code>GET /api/v2/GetRegion?regionId=<region></code>
-Example return value:
+'''Example return value''':
 <pre>{
    "id": 1,
@@ Line 33: / Line 33: @@
 }</pre>
-Notes:
+'''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.