Media Locations API

(0 reviews)

The location service is split into two areas the first covers geographic information, the second service is used to get IDs for use with the other Media Weather APIs.

1 Geographic Location Information

These calls are used to get basic geographic information on a location including its name and latitude and longitude.

There are three basic ways to access the geographic information by name, by postcode or by location.

1.1 By Name:

Description: This call passes a search string to the service for possible name matches and gets back an array of the possible locations. If the search matches a city name it will also include the suburbs for that city in the results.

API Call:

GET /locations/search?countryCode={code}&locality={text}

Parameters:

Parameter	Example	Description
countryCode	au	This is the short code of the country the location relates to. Available codes are: au – Australia. This parameter is Mandatory for Name or Postcode searches.
locality	sydney	A named location such as a metropolitan area or suburb. Accepts partial names. This parameter is Mandatory for Name searches.
maxLocations	10	The maximum number of locations to return. The returned list of locations will be truncated to include at most the number of locations specified. This parameter is Optional for Name searches.

Example:

This example would return all the matches for word “sydney” in the location database and any suburbs of the matching city “Sydney”.

GET /locations/search?countryCode=au&locality=sydney

API Response:

{
   "result":{
      "truncatedLocationList":false,
      "locations":[
         {
            "geoAdministrativeStructure":"auMetro",
            "partitions":[
               {
                  "partition":"metro",
                  "name":"Sydney"
               },
               {
                  "partition":"state",
                  "name":"New South Wales"
               }
            ],
            "postcodes":[
               "2000",
               "2001"
            ],
            "geo":{
               "latitude":-33.86885,
               "longitude":151.20933
            }
         },
         {
            "geoAdministrativeStructure":"auMetroSuburb",
            "partitions":[
               {
                  "partition":"suburb",
                  "name":"North Sydney"
               },
               {
                  "partition":"metro",
                  "name":"Sydney"
               },
               {
                  "partition":"state",
                  "name":"New South Wales"
               }
            ],
            "postcodes":[
               "2055",
               "2059",
               "2060"
            ],
            "geo":{
               "latitude":-33.83659,
               "longitude":151.20871
            }
         }
      ]
   }
}

Note: The above result has been truncated (previously to fit on the page when it was in a pdf document).

Data fields:

Field Name	Data Type	Description
truncatedLocationList	boolean	Indicates if the full list of matches is returned or whether more results are available.
locations	array	Lists the matching locations.
geoAdministrativeStructure	object	Details of the location match described as hierarchy of related locations parts, for example, a suburb located within a metropolitan area located within a state.
partitions	array	Lists the matching partitions.
partition	string	A part of the location as a location point or area, for example the related suburb part or state part.
name	string	Name of the location part, for example “State of New South Wales” for a state location part.
postcodes	array	List of post codes related to the location
geo	object	Geolocation details of the location match, including latitude and longitude.

1.2 By Postcode:

Description: This call passes a postcode string to the service for postcode matches and gets back an array of the possible locations.

API Call:

GET /locations/search?countryCode={code}&postcode={postcode}

Parameters:

Parameter	Example	Description
countryCode	au	This is the short code of the country the location relates to. Available codes are: au – Australia. This parameter is Mandatory for Name or Postcode searches.
postcode	2000	A postcode to search for. Must be a four-digit number. This parameter is Mandatory for Postcode searches.
maxLocations	10	The maximum number of locations to return. The returned list of locations will be truncated to include at most the number of locations specified. This parameter is Optional for Postcode searches.

Example:

This example would return all the matches for postcode “2000” in the location database.

GET /locations/search?countryCode=au&postcode=2000

API Response:

{
    "result":{
        "truncatedLocationList":false,
        "locations":[
            {
                "geoAdministrativeStructure":"auMetroSuburb",
                "partitions":[
                    {
                        "partition":"suburb",
                        "name":"Haymarket"
                    },
                    {
                        "partition":"metro",
                        "name":"Sydney"
                    },
                    {
                        "partition":"state",
                        "name":"New South Wales"
                    }
                ],
                "postcodes":[
                    "1240",
                    "2000"
                ],
                "geo":{
                    "latitude":-33.88096,
                    "longitude":151.20501
                }
            },
            {
                "geoAdministrativeStructure":"auMetro",
                "partitions":[
                    {
                        "partition":"metro",
                        "name":"Sydney"
                    },
                    {
                        "partition":"state",
                        "name":"New South Wales"
                    }
                ],
                "postcodes":[
                    "2000",
                    "2001"
                ],
                "geo":{
                    "latitude":-33.86885,
                    "longitude":151.20933
                }
            }
        ]
    }
}

Note: The above result has been truncated (previously to fit on the page when it was in a pdf document).

Data fields:

Field Name	Data Type	Description
truncatedLocationList	boolean	Indicates if the full list of matches is returned or whether more results are available.
locations	array	Lists the matching locations.
geoAdministrativeStructure	object	Details of the location match described as hierarchy of related locations parts, for example, a suburb located within a metropolitan area located within a state.
partitions	array	Lists the matching partitions.
partition	string	A part of the location as a location point or area, for example the related suburb part or state part.
name	string	Name of the location part, for example “State of New South Wales” for a state location part.
postcodes	array	List of post codes related to the location.
geo	object	Geolocation details of the location match, including latitude and longitude.

1.3 By Location:

Description: This call passes a set of latitude and longitude to the service and gets back the closest matching location.

API Call:

GET /locations/search?geoLocation={latitude,longitude}

Parameters:

Parameter	Example	Description
geoLocation	-33.869,151.209	Latitude and longitude in decimal degrees to 3 decimal places. This parameter is Mandatory for geolocation searches.

Example:

This example would return geographic information for Sydney.

GET /locations/search?geoLocation=-33.869,151.209

API Response:

{
    "result":{
        "truncatedLocationList":false,
        "locations":[
            {
                "geoAdministrativeStructure":"auUrban",
                "partitions":[
                    {
                        "partition":"suburb",
                        "name":"Sydney Central Business District"
                    },
                    {
                        "partition":"city",
                        "name":"City of Sydney"
                    },
                    {
                        "partition":"state",
                        "name":"State of New South Wales"
                    }
                ],
                "……""postcodes":[
                    "2000"
                ],
                "geo":{
                    "latitude":-33.86482,
                    "longitude":151.20773
                }
            }
        ]
    }
}

Data fields:

Field Name	Data Type	Description
truncatedLocationList	boolean	Indicates if the full list of matches is returned or whether more results are available.
locations	array	Lists the matching locations.
geoAdministrativeStructure	object	Details of the location match described as hierarchy of related locations parts, for example, a suburb located within a metropolitan area located within a state.
partitions	array	Lists the matching partitions.
partition	string	A part of the location as a location point or area, for example the related suburb part or state part.
name	string	Name of the location part, for example “State of New South Wales” for a state location part.
postcodes	array	List of post codes related to the location.
geo	object	Geolocation details of the location match, including latitude and longitude.

2 Weather Resources

This call is used to get mapping information on what resources are available for a location. Each forecast location has a set of resource available to it. These resources include the closest observation points, radar stations, urban forecast, coastal forecast area, district forecast region, fire danger district and tide information.

This service is accessed by latitude and longitude.

2.1 By Latitude and Longitude:

Description: This call finds the closest forecast location to the latitude and longitude specified and provides an array of mapping information for that location.

The API call returns the following mapping:

Mapping	Description
Location Information	Geographic information for the nearest forecast location including name, state, latitude, longitude and elevation.
Forecast Information	This section includes: • Urban ID for the closest urban forecast • District ID for the closest district forecast • Area ID for the closest coastal forecast (if the location is near the coast) • District ID for the closest Fire Danger Region • Tide ID for the closest tide region (if the location is near the coast)
Observation Information	This section includes: • Weather Station IDs for the 3 closest observation stations • Radar ID for the closest radar station

The IDs can then be used to access resources on the other Weather APIs.

API Call:

GET /locations/weatherResources?geoLocation={latitude,longitude}

Parameters:

Parameter	Example	Description
geoLocation	-33.869,151.209	Latitude and longitude in decimal degrees to 3 decimal places. This parameter is Mandatory.

Example:

This would return the mapping information for Sydney.

GET /locations/weatherResources?geoLocation=-33.869,151.209

API Response:

{
    "coastal":[
        {
            "key":"NSW_MW009",
            "label":"Sydney Closed Waters",
            "state":"New South Wales"
        }
    ],
    "district":[
        {
            "key":"NSW_ME001",
            "label":"Sydney",
            "state":"New South Wales"
        }
    ],
    "fdr":[
        {
            "key":"NSW_FW004",
            "label":"Greater Sydney Region",
            "state":"New South Wales"
        }
    ],
    "observations":[
        {
            "key":"94768",
            "label":"Sydney (Observatory Hill)",
            "state":"New South Wales"
        },
        {
            "key":"94769",
            "label":"Fort Denison",
            "state":"New South Wales"
        },
        {
            "key":"95766",
            "label":"Wedding Cake West",
            "state":"New South Wales"
        },
        {
            "key":"94767",
            "label":"Sydney Airport Amo",
            "state":"New South Wales"
        },
        {
            "key":"94766",
            "label":"Canterbury Racecourse Aws",
            "state":"New South Wales"
        }
    ],
    "radars":[
        {
            "key":"IDR03?radius=128",
            "label":"Wollongong (Appin) - 128k",
            "state":"NSW"
        },
        {
            "key":"IDR03?radius=512",
            "label":"Wollongong (Appin) - 512k",
            "state":"NSW"
        },
        {
            "key":"IDR04?radius=128",
            "label":"Newcastle - 128k",
            "state":"NSW"
        },
        {
            "key":"IDR04?radius=512",
            "label":"Newcastle - 512k",
            "state":"NSW"
        },
        {
            "key":"IDR28?radius=512",
            "label":"Grafton - 512k",
            "state":"NSW"
        },
        {
            "key":"IDR40?radius=512",
            "label":"Canberra (Captains Flat) - 512k",
            "state":"NSW"
        },
        {
            "key":"IDR49?radius=512",
            "label":"Yarrawonga - 512k",
            "state":"VIC"
        },
        {
            "key":"IDR53?radius=512",
            "label":"Moree - 512k",
            "state":"NSW"
        },
        {
            "key":"IDR55?radius=512",
            "label":"Wagga Wagga - 512k",
            "state":"NSW"
        },
        {
            "key":"IDR68?radius=512",
            "label":"Bairnsdale - 512k",
            "state":"VIC"
        },
        {
            "key":"IDR69?radius=512",
            "label":"Namoi (Blackjack Mountain) - 512k",
            "state":"NSW"
        },
        {
            "key":"IDR71?radius=128",
            "label":"Sydney (Terrey Hills) - 128k",
            "state":"NSW"
        },
        {
            "key":"IDR71?radius=512",
            "label":"Sydney (Terrey Hills) - 512k",
            "state":"NSW"
        },
        {
            "key":"national",
            "label":"Australian National Radar Composite"
        }
    ],
    "satellites":[
        {
            "key":"national",
            "label":"Australian National Satellite Image"
        },
        {
            "key":"nsw",
            "label":"New South Wales Satellite Image",
            "state":"NSW"
        },
        {
            "key":"tas",
            "label":"Tasmania Satellite Image",
            "state":"TAS"
        },
        {
            "key":"vic",
            "label":"Victoria Satellite Image",
            "state":"VIC"
        }
    ],
    "tides":[
        {
            "key":"NSW_TP007",
            "label":"Sydney (Fort Denison)",
            "state":"NSW"
        }
    ],
    "urban":[
        {
            "key":"SAU000164",
            "label":"Sydney",
            "state":"New South Wales"
        }
    ],
    "warnings":[
        {
            "key":"NSW",
            "label":"New South Wales",
            "state":"NSW"
        }
    ]
}

Data fields:

Field Name	Data Type	Description
coastal	array	Details of the related coastal locations including unique keys to be used when requesting weather data.
district	array	Details of the related district locations including unique keys to be used when requesting weather data.
fdr	array	Details of the related fire danger regions including unique keys to be used when requesting weather data.
observations	array	Details of the related weather stations including unique keys to be used when requesting weather data.
radars	array	Details of the related weather radars including unique keys to be used when requesting weather data.
tides	array	Details of the related tide locations including unique keys to be used when requesting weather data.
urban	array	Details of the related urban locations including unique keys to be used when requesting weather data.
warnings	array	Details of the related warning regions including unique keys to be used when requesting weather data.
key	string	Unique key of the weather location point to used when requesting weather data.
label	string	Short name of the weather location point.
state	string	The state the weather location point is in.

home

1 Geographic Location Information

1.1 By Name:

1.2 By Postcode:

1.3 By Location:

2 Weather Resources

2.1 By Latitude and Longitude:

Reviews