Client API

Overview

These notes apply to all Floodzilla services.

All object payloads are in JSON format.

All date/time fields are in UTC.

All distances (including water height) are in feet. Water heights are Feet ASL (Above Sea Level).

All water discharge numbers are in CFS (Cubic Feet per Second).

If a method name has a prefix "API", it is probably just to disambiguate it from an existing method with a similar name; eventually these will all be renamed.

The "RegionID" parameter should be added to all methods if it is not already there. The Region ID for the Snoqualmie Valley sensors is 1, and it's ok to hardcode this number for now. This parameter will eventually be used so that we can support multiple unrelated flood zones.

Gage Status and Metadata

All object definitions below are in C#, but mapping them to other languages should be straightforward.

"Stage One" and "Stage Two" refer to flood warning stages. Stage One is the level at which we consider the gage "Near Flooding". Stage Two is Flooding.

Yellow and Red are legacy names to refer to Stage One and Stage Two respectively.

Methods

APIGetLocationInfo

Returns the list of all available gages and their metadata. A lot of the metadata isn't directly useful to clients (e.g. MaxChangeThreshold is used by the system to determine if an incoming reading is invalid; clients probably don't care).

NOTE: Some of the flags per location will be changing soon as we rework how "maintenance mode" and "historical mode" are handled for gages.

Endpoint: GET floodzilla.com/api/client/APIGetLocationInfo?regionId=1

Returns: Array of ApiLocationInfo objects:

    public string Id { get; set; }
    public string LocationName { get; set; }
    public string ShortName { get; set; }
    public double? Latitude { get; set; }
    public double? Longitude { get; set; }
    public bool IsOffline { get; set; }
    public double? Rank { get; set; }
    public double? MaxChangeThreshold { get; set; }
    public double? YMin { get; set; }
    public double? YMax { get; set; }
    public double? DischargeMin { get; set; }
    public double? DischargeMax { get; set; }
    public double? DischargeStageOne { get; set; }
    public double? DischargeStageTwo { get; set; }
    public double? GroundHeight { get; set; }
    public double? YellowStage { get; set; }
    public double? RedStage { get; set; }
    public double? RoadSaddleHeight { get; set; }
    public string RoadDisplayName { get; set; }
    public string DeviceTypeName { get; set; }
    public string TimeZoneName { get; set; }
    public bool HasDischarge { get; set; }
    public int UsgsSiteId { get; set; }
    public string NoaaSiteId { get; set; }
    public bool IsCurrentlyOffline { get; set; }            // DEPRECATED: true if either IsOffline or no recent readings have come in
    public List<string> LocationImages { get; set; }
    public List<ApiFloodEvent> FloodEvents { get; set; }    // The list of historical floods that this gage has data for.

GetMetagages

A "Metagage" is a list of gages that we sometimes show aggregated data for. The primary use is for the "Sum of the 3 forks" gage on the Forecasts page, which is the sum of readings and forecasts for three separate gages at the three forks of the river.

Endpoint: GET floodzilla.com/api/client/GetMetagages?regionId=1

Returns: Array of MetagageInfo objects:

    public string Id;
    public string SiteId;
    public string Name;
    public string ShortName;
    public double StageOne;
    public double StageTwo;

GetLocations

Deprecated.

GetGageReadingsUTC

Deprecated.

Authentication

Floodzilla has its own AuthZ/AuthN API; it does not use a third party service like Auth0. The primary reason is integration with ASP.NET's built-in authentication and identity services, which the existing back end and admin tools use.

[Full documentation will be added eventually]

Subscription

The Subscription API allows clients to subscribe to various kinds of notifications (currently just email and SMS) for gages and forecast data.

Methods

[Documentation to come]