Best practices for specifying addresses and partial address in the Weather API

The Weather API and Weather Data Services page allows the user to request weather data by a location value. The location value includes the ability to specify an address or partial address. The location value can also be a latitude,longitude value, a US zip code or weather station ID.

When specifying the address, it is important that the address value includes enough information to prevent any ambiguity. For example there are many towns and cities called ‘Springfield’. What is the best way to distinguish between these cities?

Address geocoding

To find the location of an address such as ‘620 Herndon Parkway, Herndon, Virginia, 20170, USA’, we perform a step called ‘address geocoding’ which takes the pieces of the incoming address and finds the latitude and longitude for that value.

To do this, consider a full address such as ‘620 Herndon Parkway, Herndon, Virginia, 20170, USA’. When processing this address, the address is split into parts such as street number (620), street name (Herndon Parkway), city or town (Herndon), state or province (Virginia), ZIP or postal code (20170) and the country (USA). Whilst different countries have different conventions, many of these parts are similar throughout the world.

Whilst to actually walk or drive to a particular house may require a full address:

620 Herndon Parkway, Herndon, Virginia, 20170, USA

often the town alone is enough information for a reasonable weather data lookup:

 Herndon, Virginia, 20170, USA 

However, as we saw with ‘Springfield’, if we don’t include enough information, then the address geocoding lookup will fail or find the incorrect location. For US addresses, including the state name (Virginia) will likely be enough information for an accurate match. There is never harm in providing more information – the ZIP or postal code and country name will greatly improve accuracy.

Identifying incorrect values

If the information provided to the address geocoding lookup is insufficient, then an error or incorrect match will occur.

Errors are straightforward to identify. The API will return with the error message:

The geographic location of 'Bad City Name' could not be found. If this is a partial address, please consider adding addition detail such as the city, state or country.

If a match is found but it is incorrect, it’s useful to look at the output to check that is the location expected. One feature of the API is that the results include the ‘resolved address’. This is the address that the address search matched and will typically include the full address including country so help check the location value that was passed to the API.