Difference between revisions of "Gage Reading Service API"
Jump to navigation
Jump to search
| Line 17: | Line 17: | ||
|regionId | |regionId | ||
|int | |int | ||
| − | | | + | | |
|Region ID. Only one region currently exists: 1 == Snoqualmie Valley. | |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. | |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 [https://www.nwrfc.noaa.gov/rfc/ the NWRFC]. default is false. | ||
|- | |- | ||
|lastReadingId | |lastReadingId | ||
| Line 44: | Line 64: | ||
| | | | ||
|if provided, only readings newer than the specified reading will be returned. | |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). | ||
|} | |} | ||
| Line 73: | Line 98: | ||
|timestamp | |timestamp | ||
|datetime | |datetime | ||
| − | |timezone is | + | |timezone is as specified above in the returnUtc parameter |
|- | |- | ||
|waterHeight | |waterHeight | ||
Revision as of 18:26, 15 December 2020
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:
| 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:
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.
