Gage Reading Service API

Gage Reading Service

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

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

• Google Colab Notebook for Exporting Data

Parameters

The following query-string parameters are recognized:

Parameter	Type	Required	Notes
regionId	int		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.
showMissingReadings	bool		if true, "missing" readings will be included (see below). default is false.
includeStatus	bool		if true, gage status info will be included (this is probably only useful to the main Floodzilla client). default is false.
includePredictions	bool		if true, 6 hours of "predicted" readings will be returned. Predictions are currently based on linear trends, and are probably also only useful to the client. default is false.
includeForecast	bool		if true, and if this is a USGS gage, 10 days of "forecast" readings will be returned; forecast data is provided by the NWRFC. default is false.
lastReadingId	int		if provided, only readings newer than the specified reading will be returned.
returnUtc	bool		default false. If true, all timestamps in the returned data will be in UTC. Otherwise, they'll be in the region's time zone (Pacific for the SVPA).

Example request:

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

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...):

Field	Type	Notes
id	integer	unique ID for the reading; negative indicates that this is a fake "Missing" update.
timestamp	datetime	timezone is as specified above in the returnUtc parameter
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	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.

Notes

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.

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.