Media Forecast API

The forecast service covers urban, district and coastal forecasts. The forecast service also provides tides and fire danger ratings.

• Urban forecasts cover a single location and have a defined latitude and longitude.

• Urban forecasts cover a single location and have a defined latitude and longitude.

• Coastal forecasts cover an offshore region.

• Fire Danger Ratings (FDR) cover an inland region.

• Tides cover a small region around a fixed point.

The forecast service uses a key which can represent an individual location or an area. To find out what keys to use, use the Weather Resources call (see Location Services).

1 Urban or City Forecasts

These calls are spot forecasts usually for an urban or city location. The forecasts normally provided as daily forecasts which cover a 24-hour period. Forecasts for different time periods are provided using a subtype field.

The calls are accessed by an ID which identifies an individual location.

1.1 By ID:

Description: This call gets an array of the forecast data for either a single forecast location or a group of forecast locations. Currently only daily forecasts are available.

See Additional Parameters below for additional filtering options.

API Call – single forecast location:

GET /countries/{countryCode}/forecasts/urbans/{urbanID}/daily

API Call – multiple forecast locations:

GET /countries/{countryCode}/forecasts/urbans?urbanIDs=[urbanIDs]&subtype={forecastSubtype}

Parameters:

Example:

GET /countries/au/forecasts/urbans/SAU000205/daily

This example would return the urban forecast for Acacia Hills.

API Response:

This table shows the details of a 2-day urban forecast

{
    "results":[
        {
            "ID":"SAU000205",
            "city":"Acacia Hills",
            "forecasts":[
                {
                    "plainValidity":"Fri",
                    "startTime":"2017-03-17 00:00:00",
                    "endTime":"2017-03-18 00:00:00",
                    "expectedWeatherIcon":"Thunder",
                    "expectedBomIcon":"Storm",
                    "expectedWeatherDescription":"Shower or two. Possible storm",
                    "maxTemperature":34,
                    "minTemperature":24,
                    "spaStartTime":"9:10 am",
                    "spaEndTime":"4:50 pm",
                    "uvIndex":15,
                    "uvDescription":"Extreme",
                    "RainfallProbability":70,
                    "dailyRainfallRangeMin":3,
                    "dailyRainfallRangeMax":15,
                    "dailyRainfallRange":"3 to 15 mm",
                    "expectedWindDirection":"SW",
                    "expectedWindSpeedkph":7,
                    "sunRise":"06:49 am",
                    "sunRiseUTC":"20170316T211900Z",
                    "sunSet":"06:59 pm",
                    "sunSetUTC":"20170317T092900Z",
                    "moonRise":"10:20 pm",
                    "moonRiseUTC":"20170317T125000Z",
                    "moonSet":"10:21 am",
                    "moonSetUTC":"20170317T005100Z",
                    "firstLight":"06:28 am",
                    "firstLightUTC":"20170316T205800Z",
                    "lastLight":"07:21 pm",
                    "lastLightUTC":"20170317T095100Z",
                    "moonPhase":"WaningGibbous",
                    "rainDay":true
                },
                {
                    "plainValidity":"Sat",
                    "startTime":"2017-03-18 00:00:00",
                    "endTime":"2017-03-19 00:00:00",
                    "expectedWeatherIcon":"Thunder",
                    "expectedBomIcon":"Storm",
                    "expectedWeatherDescription":"Shower or two. Possible storm",
                    "maxTemperature":33,
                    "minTemperature":25,
                    "spaStartTime":"9:10 am",
                    "spaEndTime":"5:00 pm",
                    "uvIndex":16,
                    "uvDescription":"Extreme",
                    "RainfallProbability":70,
                    "dailyRainfallRangeMin":3,
                    "dailyRainfallRangeMax":15,
                    "dailyRainfallRange":"3 to 15 mm",
                    "expectedWindDirection":"N",
                    "expectedWindSpeedkph":9,
                    "sunRise":"06:49 am",
                    "sunRiseUTC":"20170317T211900Z",
                    "sunSet":"06:59 pm",
                    "sunSetUTC":"20170318T092900Z",
                    "moonRise":"11:03 pm",
                    "moonRiseUTC":"20170318T133300Z",
                    "moonSet":"11:10 am",
                    "moonSetUTC":"20170318T014000Z",
                    "firstLight":"06:28 am",
                    "firstLightUTC":"20170317T205800Z",
                    "lastLight":"07:20 pm",
                    "lastLightUTC":"20170318T095000Z",
                    "moonPhase":"WaningGibbous",
                    "rainDay":true
                }
            ]
        }
    ]
}

Data fields:

Additional Parameters

The results can be further filtered by the optional use of additional parameters.

2 District Forecasts

These calls are forecasts for a district. The forecasts normally provided as daily forecasts which cover a 24-hour period. Forecasts for different time periods are provided using a subtype field.

The calls are accessed by district IDs which are provide by the Weather Resource call. In this case the keys identify a district rather than a specific location.

2.1 By ID:

Description: This call gets an array of the forecast data for either a single district or a group of forecast districts.

See Additional Parameters below for additional filtering options.

API Call – single forecast location:

GET /countries/{countryCode}/forecasts/districts/{districtID}/daily

API Call – multiple forecast locations:

GET /countries/{countryCode}/forecasts/districts?districtIDs=[districtIDs]&subtype={forecastSubtype}

Parameters:

Example:

GET /countries/au/forecasts/districts/NSW_ME001/daily

This example would return the district forecast for Sydney NSW.

API Response:

{
    "results":[
        {
            "ID":"NSW_ME001",
            "district":"Sydney",
            "forecasts":[
                {
                    "plainValidity":"Fri",
                    "startTime":"2017-03-17 00:00:00+10",
                    "endTime":"2017-03-18 00:00:00+10",
                    "districtForecast":"Cloudy. Very high (90%) chance of showers, most likely in the morning and evening. Winds southwesterly 20 to
30 km/h tending southerly 35 to 55 km/h early in the morning and possibly reaching 45 to 65 km/h at times along the coastal fringe.",
                    "abrevDistrictForecast":"Cloudy. Very high (90%) chance of showers, most likely in morning and evening."
                },
                {
                    "plainValidity":"Sat",
                    "startTime":"2017-03-18 00:00:00+10",
                    "endTime":"2017-03-19 00:00:00+10",
                    "districtForecast":"Cloudy. Very high (near 100%) chance of showers, most likely in the morning and early afternoon. Winds
southerly 30 to 45 km/h turning east to southeasterly 15 to 25 km/h during the morning.",
                    "abrevDistrictForecast":"Cloudy. Very high (near 100%) chance of showers, most likely in morning and early afternoon."
                }
            ]
        }
    ]
}

Data fields:

Additional Parameters

The results can be further filtered by the optional use of additional parameters.

3 Coastal Forecasts

These calls are forecasts for a coastal area. The forecasts normally provided as daily forecasts which cover a 24-hour period. Forecasts for different time periods are provided using a subtype field.

The calls are accessed by area IDs which are provide by the Weather Resources call. In this case the IDs identify an offshore area rather than a specific location.

3.1 By ID:

Description: This call gets an array of the forecast data for either a single coastal area or a group of coastal areas.

See Additional Parameters below for additional filtering options.

API Call – single forecast location:

GET /countries/{countryCode}/forecasts/coastals/{coastalID}/

API Call – multiple forecast locations:

GET /countries/{countryCode}/forecasts/coastals?coastalIDs=[coastalIDs]&subtype={forecastSubtype}

Parameters:

Example:

GET /countries/au/forecasts/coastals/NSW_MW001/daily

This example would return the coastal area forecast for Eden NSW.

API Response:

{
    "results":[
        {
            "ID":"NSW_MW001",
            "coastalArea":"Eden",
            "forecasts":[
                {
                    "plainValidity":"Fri",
                    "startTime":"2017-03-17 00:00:00+10",
                    "endTime":"2017-03-18 00:00:00+10",
                    "maxSeaHeight":3,
                    "maxSwellHeight":2,
                    "wind":"S 30 to SE",
                    "windphrase":"Bcmg SE 30kt",
                    "windIcon":"Strong",
                    "coastalForecast":"Winds: Southerly 20 to 25 knots, reaching up to 30 knots during the morning and early afternoon. Winds turning
southeasterly in the late afternoon. Seas: 2 to 3 metres. Swell1: Northeasterly 1.5 to 2 metres, decreasing to 1 to 1.5 metres during the
morning. Swell2: South to southeasterly around 1 metre. Weather: Cloudy. 60% chance of showers."
                },
                {
                    "plainValidity":"Sat",
                    "startTime":"2017-03-18 00:00:00+10",
                    "endTime":"2017-03-19 00:00:00+10",
                    "maxSeaHeight":2,
                    "maxSwellHeight":2,
                    "wind":"SE 20 to ENE",
                    "windphrase":"SE at 15/20kt",
                    "windIcon":"Nil",
                    "coastalForecast":"Winds: Southeasterly 15 to 20 knots turning east to northeasterly in the late morning and early afternoon. Seas:
1 to 2 metres, decreasing to 1 metre by early evening. Swell1: Northeasterly around 1 metre, tending easterly 1.5 to 2 metres during the
morning. Swell2: Southeasterly 1.5 metres, decreasing below 1 metre around midday. Weather: Cloudy. 70% chance of showers."
                }
            ]
        }
    ]
}

Data fields:

Additional Parameters

The results can be further filtered by the optional use of additional parameters.

4 Fire Danger Ratings (FDR)

These calls are used to get the fire danger ratings for a fire district.

The calls are accessed by keys which are provide by the Weather Resources call. In this case the IDs identify a fire district.

4.1 By ID:

Description: This call gets an array of the forecast data for either a single district or a group of fire districts.

API Call – single forecast location:

GET /countries/{countryCode}/forecasts/fireDangerRatings/{fdrlID}

API Call – multiple forecast locations:

GET /countries/{countryCode}/forecasts/fireDangerRatings?fdrIDs=[fdrIDs]

Parameters:

Example:

GET /countries/au/forecasts/fireDangerRatings/TAS_FW002

This example would return the current Fire Danger Rating for Tasmania Fire District FW002.

API Response:

{
    "results":[
        {
            "ID":"TAS_FW002",
            "fireDistrict":"North East",
            "forecasts":[
                {
                    "plainValidity":"Fri",
                    "startTime":"2017-03-17 00:00:00+10",
                    "endTime":"2017-03-18 00:00:00+10",
                    "forecastFireDangerRating":"High"
                }
            ]
        }
    ]
}

Data fields:

Additional Parameters

The results can be further filtered by the optional use of additional parameters.

5 Tides

These calls are used to get tide information for a location.

The calls are accessed by tide location IDs which are provide by the Weather Resources call. In this case the location IDs identify a coastal location.

5.1 By ID:

Description: This call gets an array of the forecast data for either a single location or a group of forecast locations.

API Call – single forecast location:

GET /countries/{countryCode}/forecasts/tides/{tideID}?days={noofdays}

API Call – multiple forecast locations:

GET /countries/{countryCode}/forecasts/tides?tideIDs=[tideID]&days={noofdays}

Parameters:

number of days the forecast covers to be reduced to just the number
provided.

This parameter is Optional. Default behavior is days=7, maximum days=10.|

Example:

GET /countries/au/forecasts/tides/QLD_TP206?days=1

This example would return the current tides for location Sudbury Cay.

API Response:

{
    "results":[
        {
            "ID":"QLD_TP206",
            "location":"Sudbury Cay",
            "forecasts":[
                {
                    "startTime":"2017-01-20T00:00:00+10:00",
                    "endTime":"2017-01-20T23:59:59+10:00",
                    "tides":[
                        {
                            "type":"High",
                            "time":"2017-01-20T06:12:00+10:00",
                            "height":1.86
                        },
                        {
                            "type":"Low",
                            "time":"2017-01-20T11:37:00+10:00",
                            "height":1.44
                        },
                        {
                            "type":"High",
                            "time":"2017-01-20T16:58:00+10:00",
                            "height":1.82
                        },
                        {
                            "type":"Low",
                            "time":"2017-01-20T23:43:00+10:00",
                            "height":0.98
                        }
                    ]
                }
            ]
        }
    ]
}

Data fields:

Additional Parameters

The results can be further filtered by the optional use of additional parameters.