New Features

  • New geocoder: Woosmap. Contributed by galela. (#541)

  • New geocoder: Geokeo. Contributed by Geokeo. (#490)

Breaking Changes

  • Removed Algolia Places geocoder: the service is shut down. Contributed by mtmail. (#547)

Packaging Changes

  • Add support for Python 3.12. (#559)

  • Update maintainer email.

  • GitHub releases are now signed with GPG. (#550)

  • tests: switch from to (#551)

  • tests: use tox allowlist_externals instead of whitelist_externals. Contributed by galela. (#540)


  • RequestsAdapter: use system CA store by default instead of certifi. (#558)

  • DataBC: update service domain and endpoint. Contributed by nickpcrogers. (#557)

Code Improvements

  • Move hardcoded domains to __init__ args for all geocoders.



New Features

  • MapBox: add referer param to allow restricted api_keys. Contributed by Dennis Stritzke. (#501)

  • MapBox: add language param to geocode. Contributed by Dennis Stritzke. (#503)

  • Distance: add floor division + right multiplication operators. (#485)

  • Distance: make hashable. (#485)

  • Nominatim: add namedetails param to reverse. (#525)

  • Pelias: add countries param to geocode. (#504)

  • GoogleV3: pass the original error_message to exceptions. (#398)

Packaging Changes

  • Drop support for Python 3.5 and 3.6.

  • Add support for Python 3.10 and 3.11.

  • Relax geographiclib upper version constraint to allow 2.x. Contributed by David Hotham. (#520)

  • Raise geographiclib lower version constraint to 1.52 to fix possible ValueError in distance.geodesic due to the floating point inaccuracy. (#466)

  • Move static metadata from to setup.cfg.


  • Pelias: deprecate country_bias param, use countries instead. (#504)

  • IGNFrance: authentication is no longer accepted by the API, so passing any credentials to the geocoder class has been deprecated. These arguments should be removed. (#496)


  • Fix possible TypeError thrown by RequestsAdapter on destruction. Contributed by Philip Kahn. (#488)

  • ArcGIS: get address from LongLabel if Address is empty.

  • All geocoders: fix unexpected scientific point format for coordinates near zero in reverse geocoding. (#511)

  • BANFrance: fix broken reverse (it looks like their API has changed in a backwards-incompatible way: the lng query arg has been renamed to lon).

  • IGNFrance: fix broken geocoder due to removal of authentication in their API. (#496)

Docs Improvements

  • Add url to the GIS Stack Exchange geopy tag. Contributed by Taras Dubrava. (#516).

  • GeocodeEarth: add docs and pricing urls. Contributed by Julian Simioni. (#505).



New Features

Breaking Changes

  • Removed GeocodeFarm class: the service is very unstable. (#445)


  • GoogleV3 has been moved from geopy.geocoders.googlev3 module to The old module is still present for backwards compatibility, but it will be removed in geopy 3. (#483)


Code Improvements

Docs Improvements

  • Be more explicit in lat lon ordering. Contributed by Mateusz Konieczny. (#476)

  • Added tests for geocoders’ signatures (to ensure that all parameters are documented) and fixed docstrings which didn’t pass them. (#480)

  • Added docs for Distance class and Distance.destination() method (#473)



New Features

  • Add support for leading plus sign in the Point constructor. Contributed by Azimjon Pulatov. (#448)

Breaking Changes

  • GoogleV3: change missing api_key warning to an error. (#450)


  • Fixed an undocumented breaking change in geopy 2.0.0, where the Distance class has become abstract, thus it could no longer be used for unit conversions. (#435)

  • Photon incorrectly treated 0.0 coordinate as an empty response. Contributed by Mateusz Konieczny. (#439)

  • Nominatim: fix TypeError on empty reverse result. (#455)

Docs Improvements

  • Add Python 3.9 to the list of supported versions.

  • Bing: change postalcode to postalCode. Contributed by zhongjun-ma. (#424)

  • Nominatim: better describe what is returned in addressdetails. Contributed by Mateusz Konieczny. (#429)

  • Nominatim: better describe viewbox param behavior. Contributed by Hannes. (#454)

  • Yandex: remove attention block about requiring an API key.



geopy 2.0 is a major release with lots of cleanup and inner refactorings. The public interface of the library is mostly the same, and the set of supported geocoders didn’t change.

If you have checked your code on the latest 1.x release with enabled warnings (i.e. with -Wd key of the python command) and fixed all of them, then it should be safe to upgrade.

New Features

  • geopy.adapters module. Previously all geocoders used urllib for HTTP requests, which doesn’t support keepalives. Adapters is a new mechanism which allows to use other HTTP client implementations.

    There are 3 implementations coming out of the box:

  • Added optional asyncio support in all geocoders via AioHTTPAdapter, see the new Async Mode doc section.

  • AsyncRateLimiter – an async counterpart of RateLimiter.

  • RateLimiter is now thread-safe.

Packaging Changes

Breaking Changes

  • geopy.distance algorithms now raise ValueError for points with different altitudes, because altitude is ignored in calculations.

  • Removed geopy.distance.vincenty, use geopy.distance.geodesic instead.

  • timeout=None now disables request timeout, previously a default timeout has been used in this case.

  • Removed GoogleV3.timezone, use GoogleV3.reverse_timezone() instead.

  • Removed format_string param from all geocoders. See Specifying Parameters Once doc section for alternatives.

  • exactly_one’s default is now True for all geocoders and methods.

  • Removed service-specific request params from all __init__ methods of geocoders. Pass them to the corresponding geocode/reverse methods instead.

  • All bounding box arguments now must be passed as a list of two Points. Previously some geocoders accepted unique formats like plain strings and lists of 4 coordinates – these values are not valid anymore.

  • GoogleV3.reverse_timezone() used to allow numeric at_time value. Pass datetime instances instead.

  • reverse methods used to bypass the query if it couldn’t be parsed as a Point. Now a ValueError is raised in this case.

  • Location and Timezone classes no longer accept None for point and raw args.

  • Nominatim now raises geopy.exc.ConfigurationError when used with a default or sample user-agent.

  • Point now raises a ValueError if constructed from a single number. A zero longitude must be explicitly passed to avoid the error.

  • Most of the service-specific arguments of geocoders now must be passed as kwargs, positional arguments are not accepted.

  • Removed default value None for authentication key arguments of GeoNames, OpenMapQuest and Yandex.

  • parse_* methods in geocoders have been prefixed with _ to explicitly mark that they are private.


  • Nominatim has been moved from geopy.geocoders.osm module to geopy.geocoders.nominatim. The old module is still present for backwards compatibility, but it will be removed in geopy 3.