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)

- Add support for leading plus sign in the `.Point` constructor.

  Contributed by Azimjon Pulatov. (#448)

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

- 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 refactori…

…ngs.

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
~~~~~~~~~~~~

- :class:`.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 refactori…

…ngs.

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)