Gage Reading Service API - Revision history

GearyEppley: /* Gage Reading Service */ added link to Colab Notebook

2022-11-09T21:44:45Z

Gage Reading Service: added link to Colab Notebook

DaveSanderman: /* Gage Reading Service */

2021-11-17T16:57:56Z

Gage Reading Service

DaveSanderman at 18:27, 15 December 2020

2020-12-15T18:27:25Z

DaveSanderman: /* Gage Reading Service */

2020-12-15T18:26:10Z

Gage Reading Service

DaveSanderman: /* Gage Reading Service */

2020-12-15T16:17:02Z

Gage Reading Service

DaveSanderman at 21:52, 6 October 2020

2020-10-06T21:52:29Z

DaveSanderman at 21:51, 6 October 2020

2020-10-06T21:51:40Z

DaveSanderman: DaveSanderman moved page Gage Reading Service to Gage Reading Service API: rename for clarity

2020-08-19T01:26:50Z

DaveSanderman moved page Gage Reading Service to Gage Reading Service API: rename for clarity

DaveSanderman: Created page with "== Gage Reading Service == Floodzilla exposes a JSON web service to retrieve gage reading data. The primary endpoint is: https://readingsvc.azurewebsites.net/api/GetGageRea..."

2020-07-08T17:57:29Z

Created page with "== Gage Reading Service == Floodzilla exposes a JSON web service to retrieve gage reading data. The primary endpoint is: https://readingsvc.azurewebsites.net/api/GetGageRea..."

New page

== Gage Reading Service ==

Floodzilla exposes a JSON web service to retrieve gage reading data. The primary endpoint is:

https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC

=== Parameters ===

The following query-string parameters are recognized:

{| class="wikitable"
|'''Parameter'''
|'''Type'''
|'''Required'''
|'''Notes'''
|-
|code
|string
|X
|API key. Only current valid value is "t". Eventually users will get their own unique keys.
|-
|regionId
|int
|X
|Region ID. Only one region currently exists: 1 == Snoqualmie Valley.
|-
|id
|string
|X
|ID of the gage to read (e.g. USGS-SF17 or SVPA-17)
|-
|fromDateTime
|datetime
|
|"from" date/time in UTC. default is The Beginning Of Time.
|-
|toDateTime
|datetime
|
|"to" date/time in UTC. default is The End Of Time.
|-
|showDeletedReadings
|bool
|
|if true, deleted readings will be included (see below). default is false.
|-
|lastReadingId
|int
|
|if provided, only readings newer than the specified reading will be returned.
|}

Example request:

https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC?code=t&regionId=1&id=SVPA-17&fromDateTime=2020-01-06T16:00:07-08:00&toDateTime=2020-01-10T16:00:07-08:00&showDeletedReadings=false

=== Response ===

Example response:
{"readings":
[
{"id":178654, "timestamp":"2020-01-10T15:45:11", "waterHeight":46.05, "groundHeight":46.05, "waterDischarge":null, "batteryMillivolt":3692, "roadSaddleHeight":553.4, "rssi":-53.0, "snr":10.2, "isDeleted":false," isMissing":false},
{"id":-1200,"timestamp":"2020-01-10T15:30:11", "waterHeight":46.05, "groundHeight":46.05, "waterDischarge":null, "batteryMillivolt":3692, "roadSaddleHeight":553.4, "rssi":-53.0, "snr":10.2, "isDeleted":false, "isMissing":true}
...
]
}

Response fields (if a field isn't mentioned here, ignore it for now...):
{| class="wikitable"
|'''Field'''
|'''Type'''
|'''Notes'''
|-
|id
|integer
|unique ID for the reading
|-
|timestamp
|datetime
|UTC
|-
|waterHeight
|float
|Feet. For SVPA gages this is usually Feet Above Sea Level. For USGS gages it's an arbitrary measurement.
|-
|isMissing
|bool
|If an expected update never arrives, the service will generate "missing" updates to fill in the blanks (this is done to give a visualization of how reliable the gage is).
|-
|isDeleted
|bool
|Obviously bad readings are manually marked isDeleted by humans. If a gage is marked "offline" (e.g. for maintenance), incoming readings are automatically marked isDeleted.
|}

=== Notes ===

{{X!}} Work In Progress: All fields may change, and the service may go down at any point. All attempts will be made to keep this documentation up to date.

{{X!}} Be Patient: Currently, on the first request for a given gage, ALL gage readings are loaded into memory. This is slow. This is also temporary.

__NOTOC__

← Older revision		Revision as of 21:44, 9 November 2022
Line 4:		Line 4:

	[https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC https://prodplanreadingsvc.azurewebsites.net/api/GetGageReadingsUTC]		[https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC https://prodplanreadingsvc.azurewebsites.net/api/GetGageReadingsUTC]
		+
		+	* [https://colab.research.google.com/drive/1WPJxdeCXVDkRFdSVTY4sja8POrPa69cG Google Colab Notebook for Exporting Data]

	===Parameters===		===Parameters===

@@ Line 1: / Line 1: @@
-== Gage Reading Service ==
+==Gage Reading Service==
 Floodzilla exposes a JSON web service to retrieve gage reading data.  The primary endpoint is:
-https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC
+[https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC https://prodplanreadingsvc.azurewebsites.net/api/GetGageReadingsUTC]
-=== Parameters ===
+===Parameters===
 The following query-string parameters are recognized:
@@ Line 73: / Line 73: @@
 Example request:
-https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC?regionId=1&id=SVPA-17&fromDateTime=2020-01-06T16:00:07-08:00&toDateTime=2020-01-10T16:00:07-08:00&showDeletedReadings=false
+[https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC?regionId=1&id=SVPA-17&fromDateTime=2020-01-06T16:00:07-08:00&toDateTime=2020-01-10T16:00:07-08:00&showDeletedReadings=false https://prodplanreadingsvc.azurewebsites.net/api/GetGageReadingsUTC?regionId=1&id=SVPA-17&fromDateTime=2020-01-06T16:00:07-08:00&toDateTime=2020-01-10T16:00:07-08:00&showDeletedReadings=false]
 There is also a method called GetGageReadings().  Parameters are as above, except fromDateTime and toDateTime are expected to be in the region's timezone.  Output data still defaults to region time unless returnUtc is true.
-=== Response ===
+===Response===
 Example response:
@@ Line 115: / Line 115: @@
 |}
-=== Notes ===
+===Notes===
 {{X!}} Work In Progress: All fields may change, and the service may go down at any point.  All attempts will be made to keep this documentation up to date.

← Older revision		Revision as of 18:27, 15 December 2020
Line 74:		Line 74:

	https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC?regionId=1&id=SVPA-17&fromDateTime=2020-01-06T16:00:07-08:00&toDateTime=2020-01-10T16:00:07-08:00&showDeletedReadings=false		https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC?regionId=1&id=SVPA-17&fromDateTime=2020-01-06T16:00:07-08:00&toDateTime=2020-01-10T16:00:07-08:00&showDeletedReadings=false
		+
		+	There is also a method called GetGageReadings(). Parameters are as above, except fromDateTime and toDateTime are expected to be in the region's timezone. Output data still defaults to region time unless returnUtc is true.

	=== Response ===		=== Response ===

@@ Line 17: / Line 17: @@
 |regionId
 |int
-|X
 |Region ID.  Only one region currently exists: 1 == Snoqualmie Valley.
 |-
@@ Line 39: / Line 39: @@
+|
 |if true, deleted readings will be included (see below).  default is false.
 |-
 |lastReadingId
@@ Line 44: / Line 64: @@
+|
 |if provided, only readings newer than the specified reading will be returned.
 |}
@@ Line 73: / Line 98: @@
 |timestamp
 |datetime
-|timezone is "region time" -- represents the local time of the region that the gage is in.  For SVPA, this will be America/Los_Angeles, aka Pacific time.
+|timezone is as specified above in the returnUtc parameter
 |-
 |waterHeight

@@ Line 14: / Line 14: @@
 |'''Required'''
 |'''Notes'''
 |-
 |regionId
@@ Line 53: / Line 48: @@
 Example request:
-https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC?code=t&regionId=1&id=SVPA-17&fromDateTime=2020-01-06T16:00:07-08:00&toDateTime=2020-01-10T16:00:07-08:00&showDeletedReadings=false
+https://readingsvc.azurewebsites.net/api/GetGageReadingsUTC?regionId=1&id=SVPA-17&fromDateTime=2020-01-06T16:00:07-08:00&toDateTime=2020-01-10T16:00:07-08:00&showDeletedReadings=false
 === Response ===

@@ Line 74: / Line 74: @@
 |id
 |integer
-|unique ID for the reading
+|unique ID for the reading; negative indicates that this is a fake "Missing" update.
 |-
 |timestamp
@@ Line 90: / Line 90: @@
 |isDeleted
 |bool
-|Obviously bad readings are manually marked isDeleted by humans.  If a gage is marked "offline" (e.g. for maintenance), incoming readings are automatically marked isDeleted.
+|Readings which are obviously inaccurate are manually marked isDeleted by humans.  If a gage is marked "offline" (e.g. for maintenance), incoming readings are automatically marked isDeleted.
 |}