This app reads Alert data from The Weather Company. It uses JSON data from https://api.weather.com/v3/alerts and requires a subscription. It uses data accessed via the Weather Company Max Solution Data Package - Basic.

You can learn about updates to the app in the The Weather Company Alerts Reader Release Notes

Create Your Instance

The first time you launch the reader you will be prompted to create a new instance. You will need to provide a few pieces of information starting with:

Instance Name: this can be anything you want it to be.

Setup

Changes made will apply the next time the reader runs. The main piece of setup you need to do is to apply your API key and then select the language. The language option affects the text fields.
The Content Group should be selected so that the alerts are accessible to the correct users.

The option to Request country data when 5 or more states or provinces used is designed as a means to be more efficient with calls to the Alerts API. The app can request data for an individual area, state/province or an entire country in a single request. However if there are many alerts - the results may be paged and the app may have to make multiple requests for the data to receive it all.

Save changes by using the File menu - Save All option

Locations

You add and remove locations to be updated by the reader using the Locations tab.

1. Type the location name, airport code or geocode into the search box

2. Choose a search type - City is the default

3. Press the Search button (or the Enter key while in the location box).

4. The reader will lookup a list of possible matches and display them in the dropdown list below the search box.

5. Select the appropriate location and click the

   1. Add Location button to retrieve alerts specific to that locations area.

   2. Add Province/State button to retrieve alerts that apply the location’s entire province/state

6. It will default to putting the alerts into a Alert Group of the same name as the location

   1. You can edit this by simply clicking on the name of the Alert Group in the locations grid and typing in a new name for the Alert Group.

Add a Province or State

You can add an entire province or state instead of only specific locations to retrieve alerts.

1. Search for any location within the province/state.

2. Select a valid location from the drop down list

3. Click the Add Province/State button

Editing Alert Groups for Locations

You edit the Alert Group for a locations alerts by

1. clicking on the name of the Alert Group in the locations grid

2. typing in a new name for the Alert Group

The next time the app runs it will create the new Alert Group if it doesn’t exist in the Content Group yet and then will put the alerts into the new Alert Group.

Example

If you don’t want Telegraph Creek to have it’s own Alert Group you can change it to put the alerts into a Northern BC content group instead.

Save changes by using the File menu - Save All option

Adding Custom Locations

If you have trouble finding the alerts that you know should be there by searching for and adding locations, there is an option to add a manual location entry. Look for the Add Custom button on the Locations tab.

To figure out what area or county ID you need for your manual entry - the following method may help.

1. Turn on Debug logging in the Help - Logs menu.

2. The Then with debugging debug logging turned on run the Reader.

3. Review the log results and look for entries that indicate alerts were filtered out because of their area: Debug: FILTERING: for alert in area 046410 - Mount Forest - Arthur - Northern Wellington County

4. Note the area ID (county or zone) that was given in the log entry: (Example: 046410 )

5. Click on the Add Custom button

6. Provide the required information

   1. The Location name can be whatever you want to call it.

   2. For the State - provide the abbreviation and the full name in the 2 boxes

      1. For Canadian locations provide province code and name

7. Be sure to assign the Zone or County ID you need to correctly include the alerts you want.

   1. For Canadian locations - enter the area ID into the Zone box

   2. For U.S. locations - enter the area ID into the County box

8. Click the Save button.

9. Run the reader again to see if it successfully included your desired alerts.

Filtering

You can limit which types of alerts are saved by selecting the Severity and Significances that you want.

Save changes by using the File menu - Save All option

You selections are applied the next time the app retrieves new data.

Old Alerts

The app will automatically remove any old alerts that are no longer available in the data feed when it runs.

Sample Alert

Winter weather travel advisory in effect for today.

Hazards:
Locally heavy snowfall with total accumulations near 5 cm.
Reduced visibility at times in heavy snow.

Timing:
Today.

Discussion:
Snow is forecast to begin this morning. The snow will continue through the day before tapering to a few flurries late this afternoon or early this evening.

###

Travel may be hazardous due to sudden changes in the weather.

For road conditions and other traveller information from the Ministry of Transportation, visit https://www.ontario.ca/511 , https://www.twitter.com/511Ontario , or call 5-1-1.

Please continue to monitor alerts and forecasts issued by Environment Canada. To report severe weather, send an email to ONstorm@ec.gc.ca or tweet reports using #ONStorm.

Dynamic Fields

• Admin District

• Area Name

• Area Id

• Certainty

• Data Attribution Text (generated from other fields for ease of use)

• Disclaimer (when available)

• Effective Time Local

• Event Type

• Headline

• Message Type

• Message Type Code

• Office Name

• Response Type (if available)

• Severity

• Significance

• Source

• Urgency

Logs

You can enable Debug logs in the Help - Logs menus to get more information about what API calls are being made and which alerts are being filtered out.

2024-02-06	10:50:45	Info: 	TWC Alerts Reader Launched - Version 1.0.4.0
2024-02-06	10:50:45	Info: 	Debug logging is enabled.
2024-02-06	10:50:45	Info: 	Warnings logging is enabled.
2024-02-06	10:50:45	Info: 	Performance logging is disabled.
2024-02-06	11:14:04	Debug: 	Pulling data for Ontario from: https://api.weather.com/v3/alerts/headlines?adminDistrictCode=ON:CA&language=en-CA&format=json&apiKey=apiKey
2024-02-06	11:14:04	Debug: 	Found 4 alerts for Ontario after applying filters.
2024-02-06	11:14:04	Debug: 	Pulling data for Quebec from: https://api.weather.com/v3/alerts/headlines?adminDistrictCode=QC:CA&language=en-CA&format=json&apiKey=apiKey
2024-02-06	11:14:04	Debug: 	Found 0 alerts for Quebec after applying filters.
2024-02-06	11:14:04	Debug: 	Preparing to delete 7 alerts. DELETE FROM `story` WHERE sourceID = 81 AND `ID` IN (4771,4772,4773,4774,4775,4776,4777);
2024-02-06	11:14:04	Info: 	Deleted 7 old alerts.

API URLs Used

Alert Headlines

The alert headlines end point (https://ibm.co/v3WAHa) is currently providing all the data (Summary, Type and dynamic field values) for the alerts with the exception of the long descriptive text (saved as the Text of the alert).

To access the weather alert headlines - the app uses one of the following to get a list of alerts:

• Request by country: https://api.weather.com/v3/alerts/headlines?countryCode=<countryCode>

• Request by state/province: https://api.weather.com/v3/alerts/headlines?adminDistrictCode=<adminDistrictCode:countryCode>

• Request by area: https://api.weather.com/v3/alerts/headlines?areaId=<areaId:countryCode>

Alert Details

The alert details end point (https://ibm.co/v3WADa) is called for each alert to get the long text description.

To access the alert details the app uses:

• https://api.weather.com/v3/alerts/detail?alertId=<specificAlertId>

Locations

To search for locations (https://ibm.co/v3LPaS) the app uses one or more of the following:

• Search by name: https://api.weather.com/v3/location/search?query=atlanta

• Search by geocode: https://api.weather.com/v3/location/point?geocode=33.74,-84.39

• Search by IATA code: https://api.weather.com/v3/location/point?iataCode=ATL

• Search by ICAO code: https://api.weather.com/v3/location/point?icaoCode=KATL

• Search by Place ID: https://api.weather.com/v3/location/point?placeid=<specificID>

  • used to check for missing zone and county ID values if not available in the previous results

API Request Counting

Every time the reader runs, it first summarizes the locations to identify all the represented areas, province/states and countries. It will then try to make a single API request for a list of all applicable alerts.

• If there is only a single location requested - it makes one request for a list of alerts for that one location.

• If there are multiple locations with a common province/state then it will make a request for a list of all alerts for that common province/state.

• If there are multiple province/states then it can make a request for a list of all alerts for the country.

Once the list of alerts is received - then each alert is tested to see if it is one of the selected

• locations

• significance

• severity

If an individual alert passes all these tests then another API request is made to get the detail text of the alert and it will be saved for use.

More Details

As far as making the best use of your available API limits you should be aware of the following:

1. The app helps with this by retrieving all the alerts in 1 request instead of multiple requests for:

   • an entire province when there are multiple locations within a province

   • an entire country when there are multiple provinces represented by all the locations

2.  The efficiency of requesting a larger area is limited by the volume of total alerts available

   • If there are too many alerts to be returned in a single request then the app has to ask for the “next page” of results

     • This limit is based on the size of the response which is 1Mb of data and based on some recent sample results would mean about 500 alerts per “page”

3. To provide the full length detail in the Alert requires one API call per alert that is saved in the database.

   1. To reduce the number of saved alerts - choose only the specific Severity and Significances you want on the Filter tab in the app.

Data Provided by the initial Headlines request include (all fields except the Alert Detail Text)