API endpoint payload details and data types

The payloads that are sent to API endpoints can contain an array of JSON objects. Each JSON object is for a single asset and a single weather peril.

Note: Currently, you can only define endpoints by using the API.

Under each JSON object, the matchedConditions parameter contains weather peril details and always contains a single JSON object.

Parameters

The following parameters are the same:

eventParameter is the same as matchedConditions[0].parameterId.
eventStartTime is the same as matchedConditions[0].startTime
eventEndTime is the same as matchedConditions[0].endTime or matchedConditions[0].expireTime.

The following parameters under matchedConditions are for National Weather Service (NWS) alerts only:

phenomena
significance
detailsKey
textsId
texts

Note: All times are UNIX epoch timestamps, which is the number of milliseconds that have elapsed since 00:00:00 Coordinated Universal Time on 1 January 1970.

Endpoint payload format

The following fields are optional:

impactedFeatureIds
assetDescription
ruleDescription
featureId
phenomena
significance
detailsKey
textsId
texts
languageCode
text
values


       
[ 
  { 
    "impactedFeatureIds": []string, 
    "ruleTexts":[ 
      { 
      "name": string, 
      "description": string, 
      "detailedDescription": string, 
      "languageCode": string, 
      "default": boolean 
      } 
    ], 
    "assetIdentifier": string, 
    "assetDescription": string,
    "assetId": string,
    "ruleName": string, 
    "ruleExternalName": string,		
    "ruleDescription": string, 
    "ruleExternalId": string UUID, 
    "eventParameter": string, 
    "eventStartTime": epoch timestamp,
    "eventEndTime": epoch timestamp, 
    "matchedConditions":
    [
      { 
        "parameterId": string, 
        "timestamp": epoch timestamp, 
        "startTime": epoch timestamp, 
        "endTime": epoch timestamp, 
        "expireTime": epoch timestamp, 
        "ingestTime": epoch timestamp, 
        "ingestId": string UUID, 
        "conditionType": string, 
        "impact":{ 
          "locationHash": string, 
          "featureId": string, 
          "fullyCovered": boolean 
        }, 
        "geometryId": string UUID, 
        "phenomena": string,
        "significance": string,
        "detailsKey": string,
        "textsId": string,
        "texts":[ 
          { 
            "languageCode": string, 
            "text": string 
          } 
        ],
        "values": []double
      } 
    ]
  } 
]

End time vs expire time

Under matchedConditions, endTime and expireTime are both optional fields. NWS alerts have the endTime parameter and non-NWS alerts have the expireTime parameter.

NWS alerts use startTime and endTime parameters, where startTime is close to currentTime and endTime is greater than startTime.

Non-NWS alerts contain many weather perils, including forecast perils, where expireTime can be less than startTime. For example, the weather peril MAX_TEMP_24HR_GTE_310.93_K that alerts when the temperature forecast is above 100°F in the next 24 hours. The startTime can be anytime in the next 24 hours and the expireTime can be in the next 3 to 4 hours. In this example, expireTime indicates that this generated forecast event or prediction is valid for the next 3 to 4 hours and a new forecast event will be sent within that time period with an updated prediction. If no updated event is generated and sent, then this prediction expires.

Sample payload for NWS alerts

[
   {
      "ruleTexts":[
         {
            "name":"NWS Flood Watch",
            "description":"NWS Flood Watch",
            "detailedDescription":"An Areal Flood Watch has been issued to warn of a potential for flooding to occur 
            over a large area including streets, low-lying areas, creeks, and small streams.",
            "languageCode":"en",
            "default":true
         }
      ],      
      "assetIdentifier":"test",
      "assetDescription":"test",
      "ruleDescription":"replace with your own description",
      "ruleExternalId":"cf62f95b-358f-4dbb-9d4e-ea53ee155f91",
      "assetId":"31cf9b1b-e7e1-454f-964b-54db47befbe4",
      "eventParameter":"NWS_FLOOD_WATCH",
      "eventEndTime":1691553600000,
      "ruleName":"default_rule|NWS_FLOOD_WATCH",
      "ruleExternalName":"default_rule",
      "matchedConditions":[
         {
            "parameterId":"NWS_FLOOD_WATCH",
            "timestamp":1691506260000,
            "startTime":1691506800000,
            "endTime":1691553600000,
            "ingestTime":1691506280050,
            "ingestId":"324ddb13-ac24-4d43-9e69-268607a73a05",
            "conditionType":"VECTOR_EVENT",
            "impact":{
               "locationHash":"4caef1c",
               "fullyCovered":false
            },
            "geometryId":"a73d95d0-8b93-4355-a257-d9ac1bcb38dd",
            "phenomena":"FA",
            "significance":"A",
            "detailsKey":"1d42ef37-11ef-3f08-a17e-4e64ae62cb2c",
            "textsId":"2cbbe7f8-2e4e-418f-9608-f7417a522968",
            "texts":[
               {
                  "languageCode":"en-US",
                  "text":"...FLOOD WATCH IN EFFECT THROUGH THIS EVENING...
                  \n\n* WHAT...Flash flooding caused by excessive rainfall continues to be\npossible.
                  \n\n* WHERE...Downeast Maine, including Hancock and Washington counties.
                  \n\n* WHEN...Through this evening.
                  \n\n* IMPACTS...Excessive runoff may result in flooding of rivers,
                  \ncreeks, streams, and other low-lying and flood-prone locations.
                  \nFlooding may occur in poor drainage and urban areas.
                  \n\n* ADDITIONAL DETAILS...
                  \n- Multiple round of showers and storms will move into the area
                  \nlate this morning and continue through the evening hours.
                  \nThere is potential for some of these storms to track over the
                  \nsame areas multiple times. This could cause localized flash
                  \nflooding.
                  \n- http://www.weather.gov/safety/flood
                  \n\nPRECAUTIONARY/PREPAREDNESS ACTIONS...
                  \n\nYou should monitor later forecasts and be prepared to take action
                  \nshould Flash Flood Warnings be issued.\n\n&&\n\n"
               }
            ]
         }
      ],
      "eventStartTime":1691506800000
   }
]

Sample payloads for Non-NWS alerts

[
    {
        "ruleTexts":[
            {
                "name":"Temperature forecast > 100F in next 24hrs",
                "description":"Temperature forecast above 100F in the next 24 hours",
                "detailedDescription":"Temperature forecast above 100F in the next 24 hours.",
                "languageCode":"en",
                "default":true
            }
        ],
        "assetIdentifier":"test",
        "assetDescription":"test",
        "ruleDescription":"replace with your own description",
        "ruleExternalId":"24395f97-d940-441f-85e6-f4e6d2923b87",
        "assetId":"8ca85fb9-3b2a-40b5-ba4a-f01421d662f0",
        "eventParameter":"MAX_TEMP_24HR_GTE_310.93_K",
        "eventEndTime":1695718800000,
        "ruleName":"default_rule|MAX_TEMP_24HR_GTE_310.93_K",
        "ruleExternalName":"default_rule",
        "matchedConditions":[
            {
                "parameterId":"MAX_TEMP_24HR_GTE_310.93_K",
                "timestamp":1695705589601,
                "startTime":1695790800000,
                "expireTime":1695718800000,
                "ingestTime":1695705589601,
                "ingestId":"74e42121-2246-4213-bfde-0b1fe391f40e",
                "conditionType":"VECTOR_EVENT",
                "impact":{
                    "locationHash":"80db1bc",
                    "fullyCovered":false
                },
                "geometryId":"2d36cd11-aa13-4a6c-a47d-75b2041534d8"
            }
        ],
        "eventStartTime":1695790800000
    }
]