Bugfixes

• .Nominatim: fix broken featuretype parameter. (#564)

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 httpbin.org to httpbingo.org. (#551)
• tests: use tox allowlist_externals instead of whitelist_externals.
  Contributed by galela. (#540)

Bugfixes

• 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 setup.py to setup.cfg.

Deprecations

• .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)

Bugfixes

• 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

• .OpenCage: added annotations param.
  Contributed by mtmail. (#464)
• .Photon: added bbox param.
  Contributed by Holger Bruch. (#472)
• New geocoder: .Geocodio.
  Contributed by Jon Duckworth. (#468)
• New geocoder: .HereV7.
  Contributed by Pratheek Rebala. (#433)
• New geocoder: .What3WordsV3.
  Contributed by Saïd Tezel. (#444)
• New error class: .exc.GeocoderRateLimited. This error extends
  .exc.GeocoderQuotaExceeded and is now raised instead of it
  for HTTP 422 error code. (#479)
• .AdapterHTTPError: added headers attribute. (#479)

Breaking Changes

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

Deprecations

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

Bugfixes

• .OpenCage: improved error handling by using the default errors map
  (e.g. to raise .exc.GeocoderQuotaExceeded instead of
  .exc.GeocoderQueryError for HTTP 402 error). (#479)

Code Improvements

• .Photon: updated domain. Contributed by yrafalin. (#481)
• .IGNFrance: removed redundant check. Contributed by Miltos. (#469)
• Changed default exception type for HTTP code 408: now it is raised as
  .exc.GeocoderTimedOut instead of a more
  generic .exc.GeocoderServiceError. (#479)
• :mod:geopy.exc: extend more specific built-in exceptions where appropriate:
  classes .ConfigurationError, .GeocoderQueryError,
  .GeocoderNotFound now extend ValueError;
  .GeocoderRateLimited and .GeocoderUnavailable
  extend IOError;
  .GeocoderTimedOut extends TimeoutError. (#484)

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 :meth:.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)

Bugfixes

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

  • geopy.adapters.RequestsAdapter -- uses requests library
    which supports keepalives (thus it is significantly more effective
    than urllib). It is used by default if requests package
    is installed.
  • geopy.adapters.URLLibAdapter -- uses urllib, basically
    it provides the same behavior as in geopy 1.x. It is used by default if
    requests package is not installed.
  • geopy.adapters.AioHTTPAdapter -- uses aiohttp library.

• 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

• Dropped support for Python 2.7 and 3.4.

• New extras:

  • geopy[requests] for geopy.adapters.RequestsAdapter.
  • geopy[aiohttp] for geopy.adapters.AioHTTPAdapter.

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.

Deprecations

• .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.

This is the last feature release for the 1.x series, as geopy 2.0 has been
released. The 1.x series will not receive any new features or bugfixes
unless explicitly asked on the issue tracker.

• ADDED: Units Conversion docs section.

• ADDED: Docs now explicitly clarify that geocoding services
  don't consider altitudes. (#165)

• ADDED: Point.format_unicode method. It was always present as
  __unicode__ magic for Python 2.7, and now it can be accessed
  as a public method.

• ADDED: geopy.__version_info__ tuple which can be used to dynamically
  compare geopy version.

• ADDED: pytest --skip-tests-requiring-internet switch (might be useful
  for downstream package maintainers). (#413)

• CHANGED: Points with different altitudes now emit a warning
  in distance computations. In geopy 2.0 the warning would become
  an exception. (#387)

• CHANGED: Improved Point docs: added missing public methods,
  added more examples.

• CHANGED: Nominatim started emitting warnings for a number of sample
  user agents mentioned in the docs, such as specify_your_app_name_here.

• FIXED: IGNFrance ignored proxies with username + password auth. (#289)

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:

  • geopy.adapters.RequestsAdapter -- uses requests library
    which supports keepalives (thus it is significantly more effective
    than urllib). It is used by default if requests package
    is installed.
  • geopy.adapters.URLLibAdapter -- uses urllib, basically
    it provides the same behavior as in geopy 1.x. It is used by default if
    requests package is not installed.
  • geopy.adapters.AioHTTPAdapter -- uses aiohttp library.

• 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

• Dropped support for Python 2.7 and 3.4.

• New extras:

  • geopy[requests] for geopy.adapters.RequestsAdapter.
  • geopy[aiohttp] for geopy.adapters.AioHTTPAdapter.

Chores

• 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.

• ADDED: AlgoliaPlaces geocoder.
  Contributed by Álvaro Mondéjar. (#405)

• ADDED: BaiduV3 geocoder. (#394)

• ADDED: MapQuest geocoder.
  Contributed by Pratheek Rebala. (#399)

• ADDED: MapTiler geocoder.
  Contributed by chilfing. (#397)

• ADDED: Nominatim-based geocoders: zoom parameter
  has been added to the reverse method.
  Contributed by David Mueller. (#406)

• ADDED: GoogleV3 added support for lists in components param
  which allows to specify multiple components with the same name.
  Contributed by Pratheek Rebala. (#409)

• CHANGED: Updated links to Nominatim documentation.
  Contributed by Sarah Hoffmann. (#403)

• CHANGED: Yandex now issues a deprecation warning when lang
  parameter is specified in __init__. lang should be passed
  to geocode and reverse instead. (#350)

• CHANGED: format_string param has been marked as deprecated
  in all geocoders and will be removed in geopy 2.0.
  See the new Specifying Parameters Once doc section for alternatives.

• FIXED: IGNFrance incorrectly processed empty results: geocode
  has been raising an IndexError, reverse was returning an empty
  list. Now they both return None. (#244)

• FIXED: TomTom geocoder has been raising GeocoderInsufficientPrivileges
  exception for rate limiting errors instead of GeocoderQuotaExceeded.

• ADDED: HERE geocoder now supports the new API KEY authentication
  method. The old one is marked as deprecated and now issues a warning.
  Contributed by deeplook. (#388)

• ADDED: Nominatim-based geocoders: featuretype parameter
  has been added to the geocode method.
  Contributed by Sergio Martín Morillas. (#365)

• ADDED: Nominatim-based geocoders: namedetails parameter
  has been added to the geocode method.
  Contributed by enrique a. (#368)

• ADDED: Pelias: language parameter has been added
  to the geocode and reverse methods.
  Contributed by Armin Leuprecht. (#378)

• CHANGED: Yandex geocoder started to require API key for all requests
  since September 2019, so a warning asking to specify a key has been
  added which is issued when API key is missing.

• CHANGED (packaging): sdist now contains tests.

• FIXED: Updated link to TomTom Search API documentation.
  Contributed by Przemek Malolepszy. (#362)

• FIXED: Occasional KeyError('city') in Geolake.
  Contributed by Dmitrii K. (#373)