Geo Utils

Tools for processing of geographical data, such as geocoding.

geocode

Tools for geocoding.

geocode[source]

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: https://operations.osmfoundation.org/policies/nominatim/

Parameters:request_kwargs (dict) – Parameters for OSM API.
Returns:JSON from API response.
retry_if_not_value_error(exception)[source]

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)
geocode_dataframe(df)[source]

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.

Parameters:
  • 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
Returns:

original dataframe with lat and lon appended as floats
Return type:

(pandas.DataFrame)
generate_composite_key(city=None, country=None)[source]

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

Parameters:
  • city (str) – name of the city
  • country (str) – name of the country
Returns:

composite key
Return type:

(str)