Skip to content

Fetch warnings

Jump to bottom
Tedd edited this page Nov 14, 2019 · 57 revisions

Overview

This endpoint returns active warnings published by the Environment Agency.

Flood warning information can be retrieved from the API once per minute. More frequent requests must not be made.

API hosts

Production: https://prdfws-agw.prd.defra.cloud (available January 2020)

Training: https://trafws-agw.aws.defra.cloud (use this environment to test connections and flood warning scenarios).

API Methods

/fwis.json provides the output in json format.

/fwis.xml provides the output in the old xml format.

Request headers

Parameter name Values Description
Content-Type application/json returns warnings in JSON format
Content-Type application/xml returns warnings in XML format
x-api-key Request your keys here Authenticates access to the flood warnings api. We will provide separate keys for the production and test environment

Example

{
    "warnings": [
        {
            "situation": "DS Test 2",
            "attr": {
                "taId": 33729,
                "taCode": "065FWC2602",
                "taName": "Littlehampton East Bank",
                "taDescription": "Tidal areas of Littlehampton East Bank including Caffyn's Field, and Riverside Industrial Estate",
                "quickDial": "316035",
                "version": "5",
                "taCategory": "Flood Warning",
                "ownerArea": "Solent and South Downs",
                "createdDate": "2017-11-06T00:00:00.000Z",
                "lastModifiedDate": "2018-02-21T00:00:00.000Z",
                "situationChanged": "2019-07-23T17:15:00.000Z",
                "severityChanged": "2019-07-23T17:14:00.000Z",
                "timeMessageReceived": "2019-07-23T17:15:05.818Z",
                "severityValue": "3",
                "severity": "Severe Flood Warning"
            }
        }
    ]
}

Data dictionary

Information describing the contents when fetching warnings

Element name Description Format Values
situation A written description published by the Environment Agency for a specific target area, that provides information and guidance on the flood situation String The lake level has now peaked and is dropping in response to drier weather overnight. The level at the Lodore gauge still remains above the 1.8m flood warning level. The lake is expected to continue to fall and may drop below warning level today, Friday 23/8/19. We continue to monitor the situation closely and will update this message if the situation changes.
taID Unique ID (combination of TA Code and Version). When a new version is created, so is a taID String (50) f97b31ac0ab7aa453ff38ba6032cef1e
taCode Unique id used to identify a target area. String (50) 012FWFL43B
taName The name of the target area String (100) River Ribble at Samlesbury, beside the river including the Tickled Trout hotel and service station
taDescription A written description of the area covered String (254) Properties in Samlesbury next to the River Ribble, and the Tickled Trout hotel and service station
quickDial The quick dial code used to access recorded messages form Floodline over the phone String (50) 316035
version A new version is created whenever a ‘content’ update is made to the target area. A new version is not created when the target area changes severity. Int 5
taCategory Warning category String (50) Current categories are Flood Warning, Flood Warning Rapid Response, Flood Alert, Flood Alert Groundwater, Flood Warning Groundwater. Additional categories may be added in the future, but will all start either "Flood Alert" or "Flood Warning"
ownerArea The name of the Area team at the Environment Agency who are responsible for the warning message String (50) Cumbria and Lancashire
createdDate The date and time the current version of the target area was created date/time (UTC) 2017-11-06T00:00:00.000Z
lastModifiedDate The date and time the current version of the target was last modified date/time (UTC) 2017-12-06T00:00:00.000Z
situationChanged The date and time the situation was changed date/time (UTC) 2019-08-06T00:00:00.000Z
severityChanged The date and time the severity was changed date/time (UTC) 2019-08-06T00:00:00.000Z
timeMessageReceived The date and time the warning message was received by the API gateway date/time (UTC) 2019-08-06T00:00:00.000Z
severityValue an int value that maps to severity int 1 = flood alert, 2 = flood warning, 3 = severe flood warning, 4 = warning no longer in force
severity a description of the flooding severity String (50) flood alert, flood warning, severe flood warning, warning no longer in force

If you're consuming fwis.xml (ENT_7005 on FWFI or via fwis.nfwc.ea.gov/xml)

If you're currently consuming fwis.xml (ENT_7005 on FWFI or via fwis.nfwc.ea.gov/xml), be aware of these changes when switching:

Element name in flood warnings API Comments Element used in fwis.xml or fwis.nfwc.ea.gov/xml
situation The flood warnings API publishes English language only rim_english
taID Does not feature in fwis.xml or fwis.nfwc.ea.gov/xml N/A
taCode N/A fwacode
taName N/A description
taDescription Does not feature in fwis.xml or fwis.nfwc.ea.gov/xml N/A
quickDial Does not feature in fwis.xml or fwis.nfwc.ea.gov/xml N/A
version Does not feature in fwis.xml or fwis.nfwc.ea.gov/xml N/A
taCategory Does not feature in fwis.xml or fwis.nfwc.ea.gov/xml N/A
ownerArea N/A area
createdDate Does not feature in fwis.xml or fwis.nfwc.ea.gov/xml N/A
lastModifiedDate Does not feature in fwis.xml or fwis.nfwc.ea.gov/xml N/A
situationChanged N/A rim_changed
severityChanged N/A severity_changed
timeMessageReceived N/A timeraised
severityValue The mapping to warning severity has changed. See the data dictionary for details severityvalue

Elements used in fwis.xml and fwis.nfwc.ea.gov/xml that are not used in the flood warnings API

  • Warningkey
  • Region
  • Fwakey
  • Rim_welsh
  • Language

Requesting support

When something goes wrong, it's likely that one of these HTTP status codes will be returned:

Fault codes What the code means
503 The service is unavailable
403 Unauthorised access

Before requesting support

  • Check you're using the API key issued to you by the Environment Agency. If you don't have a key, you can request one here
  • Check your own IT infrastructure is not at fault, including internet availability
  • Have some way of recording the incident number given to you by the Environment Agency

When raising a support call, you'll need this information:

  • organisation name
  • contact name during the fault resolution process
  • contact phone number and email address that the Environment Agency can use for correspondence
  • fault codes you are seeing and/or a description of the fault, with screen shots if possible

Raising a support call

To ensure the call is handled correctly you should state that the fault relates to the flood warnings API service and contact our helpdesk on 0330 303 4424.

Enquiries which have no service impact should be emailed to floodwarningservices@environment-agency.gov.uk.

We aim to respond to these enquiries within 5 working days.

What happens after a support call has been raised?

When a fault is logged you'll be given an incident reference. You'll need this in any further communications with the Environment Agency.

Is there anything wrong with this page?

Tell us by emailing floodwarningservices@environment-agency.gov.uk

Clone this wiki locally