Geo Utils

Tools for processing of geographical data, such as geocoding.


Tools for geocoding.


Geocoder using the Open Street Map Nominatim API.

If there are multiple results the first one is returned (they are ranked by importance). The API usage policy allows maximum 1 request per second and no multithreading:

Parameters:request_kwargs (dict) – Parameters for OSM API.
Returns:JSON from API response.

Forces retry to exit if a valueError is returned. Supplied to the ‘retry_on_exception’ argument in the retry decorator.

Parameters:exception (Exception) – the raised exception, to check
Returns:False if a ValueError, else True
Return type:(bool)

A wrapper for the geocode function to process a supplied dataframe using the city and country.

Parameters:df (dataframe) – a dataframe containing city and country fields.
Returns:a dataframe with a ‘coordinates’ column appended.
geocode_batch_dataframe(df, city='city', country='country', latitude='latitude', longitude='longitude', query_method='both')[source]

Geocodes a dataframe, first by supplying the city and country to the api, if this fails a second attempt is made supplying the combination using the q= method. The supplied dataframe df is returned with additional columns appended, containing the latitude and longitude as floats.

  • df (pandas.DataFrame) – input dataframe
  • city (str) – name of the input column containing the city
  • country (str) – name of the input column containing the country
  • latitude (str) – name of the output column containing the latitude
  • longitude (str) – name of the output column containing the longitude
  • query_method (int) – query methods to attempt: ‘city_country_only’: city and country only ‘query_only’: q method only ‘both’: city, country with fallback to q method

original dataframe with lat and lon appended as floats

Return type:


generate_composite_key(city=None, country=None)[source]

Generates a composite key to use as the primary key for the geographic data.

  • city (str) – name of the city
  • country (str) – name of the country

composite key

Return type: