Geocoding library for Python.

geopy

Last update: Dec 30, 2022

Related tags

Overview

geopy

geopy is a Python client for several popular geocoding web services.

geopy makes it easy for Python developers to locate the coordinates of addresses, cities, countries, and landmarks across the globe using third-party geocoders and other data sources.

geopy includes geocoder classes for the OpenStreetMap Nominatim, Google Geocoding API (V3), and many other geocoding services. The full list is available on the Geocoders doc section. Geocoder classes are located in geopy.geocoders.

geopy is tested against CPython (versions 3.5, 3.6, 3.7, 3.8, 3.9) and PyPy3. geopy 1.x line also supported CPython 2.7, 3.4 and PyPy2.

Installation

Install using pip with:

pip install geopy

Or, download a wheel or source archive from PyPI.

Geocoding

To geolocate a query to an address and coordinates:

>>> from geopy.geocoders import Nominatim
>>> geolocator = Nominatim(user_agent="specify_your_app_name_here")
>>> location = geolocator.geocode("175 5th Avenue NYC")
>>> print(location.address)
Flatiron Building, 175, 5th Avenue, Flatiron, New York, NYC, New York, ...
>>> print((location.latitude, location.longitude))
(40.7410861, -73.9896297241625)
>>> print(location.raw)
{'place_id': '9167009604', 'type': 'attraction', ...}

To find the address corresponding to a set of coordinates:

>>> from geopy.geocoders import Nominatim
>>> geolocator = Nominatim(user_agent="specify_your_app_name_here")
>>> location = geolocator.reverse("52.509669, 13.376294")
>>> print(location.address)
Potsdamer Platz, Mitte, Berlin, 10117, Deutschland, European Union
>>> print((location.latitude, location.longitude))
(52.5094982, 13.3765983)
>>> print(location.raw)
{'place_id': '654513', 'osm_type': 'node', ...}

Measuring Distance

Geopy can calculate geodesic distance between two points using the geodesic distance or the great-circle distance, with a default of the geodesic distance available as the function geopy.distance.distance.

Here's an example usage of the geodesic distance:

>>> from geopy.distance import geodesic
>>> newport_ri = (41.49008, -71.312796)
>>> cleveland_oh = (41.499498, -81.695391)
>>> print(geodesic(newport_ri, cleveland_oh).miles)
538.390445368

Using great-circle distance:

>>> from geopy.distance import great_circle
>>> newport_ri = (41.49008, -71.312796)
>>> cleveland_oh = (41.499498, -81.695391)
>>> print(great_circle(newport_ri, cleveland_oh).miles)
536.997990696

Documentation

More documentation and examples can be found at Read the Docs.

Comments

Use the more accurate distance routines in geographiclib, if available.

This follows up on an E-mail thread on [email protected] from September 2011, "Patch to provide GeodesicDistance for geopy". It provides a more accurate solution for geodesics compared to Vincenty by using the python package geographiclib if it is available. In addition the distance calculation always succeeds. It's possible that it addresses issue #140 also. Still to do: add tests (but I haven't figured out the testing framework yet).

opened by cffk 22

Insufficient Priveleges for Nominatim

When using Nominatim, we get an geopy.exc.GeocoderInsufficientPrivileges exception, even though Nominatim should not require account credentials:

>>> geolocator = Nominatim()
>>> geolocator.geocode("Washington, DC", timeout=10) 
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/local/lib/python2.7/dist-packages/geopy/geocoders/osm.py", line 191, in geocode
    self._call_geocoder(url, timeout=timeout), exactly_one
  File "/usr/local/lib/python2.7/dist-packages/geopy/geocoders/base.py", line 147, in _call_geocoder
    raise ERROR_CODE_MAP[code](message)
geopy.exc.GeocoderInsufficientPrivileges: HTTP Error 403: Forbidden

Can anyone else confirm?

opened by solumos 22

Added possibility to add a custom http request user agent header
My application that uses geopy was blocked by Nominatim as geopy uses the standard user agent header for requests provided by urllib (Python-urllib/2.7). Nominatim requires to add an identifying user agent header per application in order to be able to track and block requests if needed.

I now added in this PR a default header in the base geocoder class: User-Agent: geopy/#version where #version is the current geopy version (e.g "geopy/1.9.1")

This is now added to every request and every geocoder inheriting from the 'Geocoder' base class. This should be much better, as it is much easier for services to be able to track which request come from where. Now every service is able to distinguish geopy requests from non geopy requests.

In addition I added the possibility to pass in a custom user agent string to the Nominatim geocoder class:

geocoder = Nominatim( user_agent='my_user_agent/1.0' ) self.assertEqual(geocoder.headers['User-Agent'], 'my_user_agent/1.0')

This should help to prevent quite some blockings`and bans from Nominatim, as now they are able to distinguish bad requests from good request based on the user agent headers and only block those, which have e.g a standard user agent like "geopy/1.9.1" or even "Python-urllib/2.7" and spare those requests identifying with a specific user agent like "GoodApp/0.1" as long as all "GoodApp/0.1" requests respect the Nominatim terms of usage.

I also added tests for it and thereby fixed the tests for ignfrance which were not able to pass tests without api key credentials even they should be skipped in that case.
opened by sebastianneubauer 17
Nominatim HTTP Error 403: Forbidden for default User-Agent

Nominatim API seems to block the default User-Agent: Python-urllib/3.5 now: HTTP Error 403: Forbidden.

Looking at the code the default User-Agent should be geopy/1.11.0? I've tried to set own user-agent by: Nominatim(user_agent='MyApp/1.2.3') but the request has still the user agent User-Agent: Python-urllib/3.5 and it fails with HTTP 403. So, the user-agent param does not work properly.

Edit: duplicate to #185 and probably solved by #184. Leaving this opened, since the Nominatim has started to block these requests just recently. Just to prevent other folks to duplicate the issue like me.

opened by xmedeko 15
Add HERE geocoder

This is a wrapper around HERE's geocoder API (incl. reverse geocoding) which can also be used to retrieve various kinds of polygons (one test is included). Additional tests might follow later.

opened by deeplook 12
Here geocoder authentication issues
Maybe i am mistaken but the Here API wrapper inside geopy is outdated, it seems it cant support the api_key argument which is the current way of authenticating with the here api alongside the app_id.

for example this fail as the current class uses app_id and app_code:

from geopy.geocoders import Here as GeopyHere client = GeopyHere(api_key="YOUR_API_KEY", app_id="YOUR_APP_ID") client.geocode("Shimogyo")

Basically all new apps don't receive an app_code so they cant work with geopy's wrapper. is it planned in a future release or a PR is welcome? Here docs about the app_code stopping:
opened by kenseii 11
Is this project being maintained?

Hi,

I have found several bug with this code, specifically around the implementation of the opencage geocoder. I'm happy to put in time on fixing them and submit pull requests, but am concerned that this project seems unmaintained.

The README says "build: failing" which isn't a good sign, there are 59 issues and 31 pull requests sitting open, last commit September 2016.

Please let me know. Many thanks!

opened by freyfogle 11
Distance calculation takes (y, x) instead of (x, y)
So the issue is that distance caluclation (vincenty and great_circle) take arguments in the form of ((y, x), (y, x)) instead of ((x, y), (x, y)). The convention followed by Geopy is consistent with the idea of (Latitude, Longitude), but is not conversant with Shapely or Fiona's idea of the same. Shapely and Fiona will return (x, y), or (Longitude, Latitude), and I think Geopy should accept that format as default. Perhaps have a Boolean switch that takes the other format. For example, the following pseudocode:

def vincenty(p1, p2, xy=True): if xy: p1 = reversed(p1) p2 = reversed(p2) # And the rest of the algorithm as usual.

IMHO, this would save a considerable amount of headache. Most answers on Stack Exchange are also oblivious to this (eg: http://gis.stackexchange.com/questions/4022/looking-for-a-pythonic-way-to-calculate-the-length-of-a-wkt-linestring).
has open PR
opened by dragonator4 11
Persistent connections

It would be very nice to use something like requests.Session to keep connections persistent hence to geocode faster multiple objects.

Is it possible to add this?

opened by zeljkobekcic 10
Error in geocoding example in README?

The first example in the README for v1.1.0 appears to have an error. If I run the example verbatim from the README, I get:

geolocator = Nominatim() location = geolocator.geocode("175 5th Avenue NYC") Traceback (most recent call last): File "", line 1, in File "/sw/lib/python2.7/site-packages/geopy/geocoders/osm.py", line 192, in geocode self._call_geocoder(url, timeout=timeout), exactly_one File "/sw/lib/python2.7/site-packages/geopy/geocoders/base.py", line 160, in _call_geocoder raise GeocoderServiceError(message) geopy.exc.GeocoderServiceError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:581)>

The example works without error if I add "scheme='http'" to the call to Nominatim(). E.g.

geolocator = Nominatim(scheme='http') location = geolocator.geocode("175 5th Avenue NYC") print(location.address) Flatiron Building, 175, 5th Avenue, Flatiron, New York, NYC, New York, 10010, United States of America

opened by khorton 10
Ability/methodology of extending Geocoder parameters

Some geocoding services provide very rich APIs (in terms of parameters), while geopy's geocoders usually implement just a subset of it.

We need to come up with a methodology of letting people pass arbitrary parameters if they need to, probably at a cost of possible code breakage on upgrades, as underlying API versions are getting updated in minor (not major) geopy releases, as stated in the semver section of the doc.

Currently in this situation I'd suggest to open a PR adding the parameters you're missing. For a quick and dirty solution, you might be okay with extending the geocoder class and overloading geocode/reverse and _call_geocoder methods with passing extra data via threading.local() (but please don't do this unless you really have to).

Relevant discussion: https://github.com/geopy/geopy/pull/304#discussion_r195167065 Other occurrences: #222

opened by KostyaEsmukov 9
Updated databc.py

Updated the link to the BC Address Geocoder documentation and the values for the geocode_path and domain variables. The previous geocoder url is deprecated (https://apps.gov.bc.ca/pub/geocoder) and has been replaced by the following -> https://geocoder.api.gov.bc.ca. Parameters and API response remain the same.

opened by BK01 0
Add pyproject.toml and several other build-related changes
Define a PEP 518 build-system with pyproject.toml

Move isort configuration to preferred pyproject.toml

Migrate other project metadata from setup.py to setup.cfg

Add project URLs, change download URL

Use "python -m build" for "make dist"

Add "twine check --strict" for "make pypi-release"
opened by mwtoews 0
Add missing credentials to CI
geopy tests against tens of geocoding services which regularly change their usage policies and disable/revoke api tokens. This issue is there to track the current status until the 100% of geocoders would be tested again.

The following credentials are currently missing in CI:

[ ] algolia -- started to require my billing information which I'm not willing to provide.

[ ] azure -- my account has been disabled.

[ ] mapquest + openmapquest -- "There was an error fetching your plan's information", sent a support issue via a feedback form.

[ ] opencage -- ??? "invalid password".

[x] pickpoint -- my account has been switched to a Trial one, sent an email to [email protected].
opened by KostyaEsmukov 2
Feature request: add support for endpoint `mapbox.places-permanent`

It appears that only the mapbox.places endpoint is accessible through Geopy. Would be useful to access the mapbox.places-permanent endpoint too; see https://docs.mapbox.com/api/search/geocoding/#endpoints .

opened by araichev 0
Allowing different mapbox endpoints.

The mapbox api provides different endpoints that are differentiated by the url path. Adding an endpoint parameter that is used to template the api path and providing a default parameter to preserve the current behaviour. Doing so allows us to create a mapbox geocoder and call the mapbox.places-permanent endpoint.

opened by dennisstritzke 1

Releases(2.3.0)

2.3.0(Nov 13, 2022)
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).

Source code(tar.gz)
Source code(zip)
2.2.0(Jul 11, 2021)
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)

Source code(tar.gz)
Source code(zip)
2.1.0(Dec 27, 2020)
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.

Source code(tar.gz)
Source code(zip)
2.0.0(Jun 27, 2020)
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.

Source code(tar.gz)
Source code(zip)
1.23.0(Jun 27, 2020)
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)

Source code(tar.gz)
Source code(zip)
2.0.0rc1(Jun 21, 2020)
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.

Source code(tar.gz)
Source code(zip)
1.22.0(May 11, 2020)
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.

Source code(tar.gz)
Source code(zip)
1.21.0(Feb 2, 2020)
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)

Source code(tar.gz)
Source code(zip)
1.20.0(Feb 2, 2020)
FIXED: MapBox's geocode method was ignoring the exactly_one parameter. Contributed by TheRealZeljko. (#358)

FIXED: The resulting Location's raw attribute in MapBox erroneously contained a single string instead of a full service response. This might be considered a breaking change (although it's unlikely that the previous raw value was usable at all). Contributed by Sergey Lyapustin and TheRealZeljko. (#354)

Source code(tar.gz)
Source code(zip)
1.19.0(Mar 26, 2019)
ADDED: GoogleV3: place_id arg has been added to the geocode method. Contributed by Mesut Öncel. (#348)

ADDED: Geolake, GeoNames, MapBox, OpenCage, OpenMapQuest, Nominatim and PickPoint geocoders now also accept Python lists of countries instead of just a single string. (#349)

CHANGED: geocode-specific args have been moved to geocode methods from __init__, and the corresponding __init__ args has been deprecated. The affected geocoders are: GeocodeEarth, GeoNames, OpenMapQuest, Nominatim, Pelias, PickPoint, LiveAddress. (#350)

FIXED: OpenCage's country arg was not respected. Contributed by Sebastian Illing. (#342)

FIXED: GoogleV3 has erroneously been issuing a warning about a missing api key when using premier. Contributed by Mike Hansen. (#345)

Source code(tar.gz)
Source code(zip)
1.18.1(Dec 16, 2018)
FIXED: GeoNames.reverse_timezone didn't process errors returned by API and instead was always raising obscure KeyError exceptions.

FIXED: GeoNames.reverse_timezone raised KeyError for points which don't have an assigned Olson timezone ID (e.g. Antarctica). Now a valid geopy.Timezone is returned for such, where pytz timezone is created as pytz.FixedOffset.

FIXED: GoogleV3.reverse_timezone raised KeyError for points which don't have an assigned Olson timezone ID (e.g. Antarctica). Now None is returned for such requests, as Google doesn't provide any meaningful data there.

Source code(tar.gz)
Source code(zip)
1.18.0(Dec 2, 2018)
The work on geopy 2.0 has started, see the new geopy 2.0 doc section for more info. geopy 2.0 will drop support for Python 2.7 and 3.4. To ensure a smoother transition from 1.x to 2.0, make sure to check your code with warnings enabled (i.e. run python with the -Wd switch).

ADDED: Geolake geocoder. Contributed by Yorick Holkamp. (#329)

ADDED: BANFrance (Base Adresse Nationale) geocoder. Contributed by Sébastien Barré. (#336)

ADDED: TomTom and AzureMaps: language param has been added to the reverse method.

ADDED: Geonames geocoder now supports both findNearbyPlaceName and findNearby reverse geocoding methods, as chosen by a new find_nearby_type parameter of the reverse method. Contributed by svalee. (#327)

ADDED: Geonames geocoder now supports returning a timezone for a particular Point via a new reverse_timezone method. Contributed by svalee. (#327)

ADDED: Geonames geocoder's reverse method now supports new parameters: lang and feature_code. Contributed by svalee. (#327)

ADDED: Geonames now supports scheme parameter. Although the service itself doesn't yet support https, it will be possible to enable https via this new parameter as soon as they add the support, without waiting for a new release of geopy.

CHANGED: Geonames now builds Location.address differently: previously it looked like Kreuzberg, 16, DE, now it looks like Kreuzberg, Berlin, Germany.

CHANGED: All warnings now specify a correct stacklevel so that the warnings point at the place in your code that triggered it, instead of the geopy internals.

CHANGED: All warnings with UserWarning category which will be removed in geopy 2.0 now have the DeprecationWarning category.

CHANGED: geopy.extra.rate_limiter.RateLimiter is no longer an experimental API.

CHANGED: GoogleV3.timezone now issues a deprecation warning when at_time is a number instead of a datetime. In geopy 2.0 this will become an exception.

CHANGED: GoogleV3.timezone method is now deprecated in favor of GoogleV3.reverse_timezone, which works exactly the same, except that it returns a new geopy.Timezone object, which is a wrapper for pytz timezone similarly to geopy.Location. This object also contains a raw response of the service. GoogleV3.timezone will be removed in geopy 2.0. (#332)

CHANGED: Point constructor silently ignored the tail of the string if it couldn't be parsed, now it is not ignored. For example, 75 5th Avenue, NYC, USA was parsed as Point(75, 5), but now it would raise a ValueError exception.

FIXED: GoogleV3.timezone method didn't process errors returned by the API.

Source code(tar.gz)
Source code(zip)
1.17.0(Sep 13, 2018)
ADDED: OpenMapQuest how inherits from Nominatim. This adds support for all parameters and queries implemented in Nominatim (such as reverse geocoding). (#319)

ADDED: Nominatim-based geocoders now support an extratags option. Contributed by Oleg. (#320)

ADDED: Mapbox geocoder. Contributed by William Hammond. (#323)

ADDED: ArcGIS now supports custom domain and auth_domain values. Contributed by Albina. (#325)

ADDED: Bodies of unsuccessful HTTP responses are now logged with INFO level.

CHANGED: Reverse geocoding methods now issue a warning for string queries which cannot be used to construct a Point instance. In geopy 2.0 this will become an exception.

CHANGED: GoogleV3 now issues a warning when used without an API key.

CHANGED: Parameters accepting bounding boxes have been unified to accept a pair of diagonal points across all geopy. Previous formats are still supported (until geopy 2.0) but now issue a warning when used.

CHANGED: Path part of the API urls has been moved to class attributes in all geocoders, which allows to override them in subclasses. Bing and What3Words now store api urls internally differently.

FIXED: TomTom and AzureMaps have been passing boolean values for typeahead in a wrong format (i.e. 0 and 1 instead of false and true).

Source code(tar.gz)
Source code(zip)
1.16.0(Jul 28, 2018)
ADDED: geopy.extra.rate_limiter.RateLimiter class, useful for bulk-geocoding a pandas DataFrame. See also the new Usage with Pandas doc section. (#317)

CHANGED: Nominatim now issues a warning when the default user_agent is used against nominatim.openstreetmap.org. Please always specify a custom user-agent when using Nominatim. (#316)

Source code(tar.gz)
Source code(zip)
1.15.0(Jul 15, 2018)
ADDED: GeocodeEarth geocoder based on Pelias (ex-Mapzen). (#309)

ADDED: TomTom and AzureMaps (based on TomTom) geocoders. (#312)

ADDED: HERE geocoder. Contributed by deeplook. (#304)

ADDED: Baidu now supports authentication using SK via a new security_key option. Contributed by tony. (#298)

ADDED: Nominatim's and Pickpoint's view_box option now accepts a list of Points or numbers instead of just stringified coordinates. Contributed by svalee. (#299)

ADDED: Nominatim and Pickpoint geocoders now support a bounded option, which restricts results to the items strictly contained within the view_box. Contributed by Karimov Dmitriy. (#182)

ADDED: proxies param of geocoders can now accept a single string instead of a dict. See the updated docs for the geopy.geocoders.options.default_proxies attribute for more details. Contributed by svalee. (#300)

CHANGED: Mapzen has been renamed to Pelias, domain parameter has been made required. (#309)

CHANGED: What3Words API has been updated from v1 to v2. Please note that Location.raw results have changed due to that. Contributed by Jonathan Batchelor. (#226)

FIXED: Baidu mistakenly didn't process the returned errors correctly. Contributed by tony. (#298)

FIXED: proxies={} didn't reset system proxies as expected.

Source code(tar.gz)
Source code(zip)
1.14.0(May 13, 2018)
This release contains a lot of public API cleanup. Also make sure to check out the updated docs! A new Semver doc section has been added, explaining the geopy's policy on breaking changes.

ADDED: Nominatim geocoder now supports an addressdetails option in the reverse method. Contributed by Serphentas. (#285)

ADDED: ArcGIS geocoder now supports an out_fields option in the geocode method. Contributed by Jonathan Batchelor. (#227)

ADDED: Yandex geocoder now supports a kind option in the reverse method.

ADDED: Some geocoders were missing format_string option. Now all geocoders support it.

ADDED: geopy.distance.lonlat function for conveniently converting (x, y, [z]) coordinate tuples to the Point instances, which use (y, x, [z]). Contributed by svalee. (#282)

ADDED: geopy.geocoders.options object, which allows to configure geocoder defaults (such as User-Agent, timeout, format_string) application-wide. (#288)

ADDED: Support for supplying a custom SSL context. See docs for geopy.geocoders.options.default_ssl_context. (#291)

ADDED: Baidu geocoder was missing the exactly_one option in its reverse method.

ADDED: GeocodeFarm now supports a scheme option.

CHANGED: Baidu and Yandex geocoders now use https scheme by default instead of http.

CHANGED: ArcGIS geocoder was updated to use the latest API. Please note that Location.raw results for geocode have changed a little due to that. Contributed by Jonathan Batchelor. (#227)

CHANGED: Explicitly passed timeout=None in geocoder calls now issues a warning. Currently it means "use geocoder's default timeout", while in geopy 2.0 it would mean "use no timeout". (#288)

CHANGED: GoogleV3 geocode call now supports components without query being specified. (#296)

CHANGED: GeoNames, GoogleV3, IGNFrance, OpenCage and Yandex erroneously had exactly_one=False by default for reverse methods, which must have been True. This behavior has been kept, however a warning will be issued now unless exactly_one option is explicitly specified in reverse calls for these geocoders. The default value will be changed in geopy 2.0. (#295)

CHANGED: Point now throws a ValueError exception instead of normalizing latitude and tolerating NaN/inf values for coordinates. (#294)

CHANGED: Vincenty usage now issues a warning. Geodesic should be used instead. Vincenty is planned to be removed in geopy 2.0. (#293)

CHANGED: ArcGIS wkid option for reverse call has been deprecated because it was never working properly, and it won't, due to the coordinates normalization in Point.

FIXED: ArcGIS and What3Words did not respect exactly_one=False. Now they respect it and return a list of a single location in this case.

FIXED: ArcGIS was throwing an exception on empty response of reverse. Now None is returned, as expected.

FIXED: GeocodeFarm was raising an exception on empty response instead of returning None. Contributed by Arthur Pemberton. (#240)

FIXED: GeocodeFarm had missing Location.address value sometimes.

REMOVED: geopy.geocoders.DEFAULT_* constants (in favor of geopy.geocoders.options.default_* attributes). (#288)

REMOVED: YahooPlaceFinder geocoder. (#283)

REMOVED: GeocoderDotUS geocoder. (#286)

Source code(tar.gz)
Source code(zip)
1.13.0(Apr 12, 2018)
ADDED: Pickpoint geocoder. Contributed by Vladimir Kalinkin. (#246)

ADDED: Bing geocoder: additional parameters for geocoding (culture and include_country_code). Contributed by Bernd Schlapsi. (#166)

ADDED: Point and Location instances are now picklable.

ADDED: More accurate algorithm for distance computation geopy.distance.geodesic, which is now a default geopy.distance.distance. Vincenty usage is now discouraged in favor of the geodesic. This also has added a dependency of geopy on geographiclib package. Contributed by Charles Karney. (#144)

ADDED: Nominatim geocoder now supports a limit option and uses limit=1 for exactly_one=True requests. Contributed by Serphentas. (#281)

CHANGED: Point now issues warnings for incorrect or ambiguous inputs. Some of them (namely not finite values and out of band latitudes) will be replaced with ValueError exceptions in the future versions of geopy. (#272)

CHANGED: Point now uses fmod instead of % which results in more accurate coordinates normalization. Contributed by svalee. (#275, #279)

CHANGED: When using http proxy, urllib's install_opener was used, which was altering urlopen call globally. It's not used anymore.

CHANGED: Point now raises ValueError instead of TypeError when more than 3 arguments have been passed.

FIXED: Point was raising an exception when compared to non-iterables.

FIXED: Coordinates of a Point instance changed via __setitem__ were not updating the corresponding lat/long/alt attributes.

FIXED: Coordinates of a Point instance changed via __setitem__ were not being normalized after assignment. Note, however, that attribute assignments are still not normalized. (#272)

FIXED: Distance instances comparison was not working in Python3.

FIXED: Yandex geocoder was sending API key with an incorrect parameter.

FIXED: Unit conversions from feet were incorrect. Contributed by scottessner. (#162)

FIXED: Vincenty destination function had an error in the formula implementation. Contributed by Hanno Schlichting. (#194)

FIXED: Vincenty was throwing UnboundLocalError when difference between the two longitudes was close to 2*pi or either of them was NaN. (#187)

REMOVED: geopy.util.NullHandler logging handler has been removed.

Source code(tar.gz)
Source code(zip)
1.12.0(Mar 13, 2018)
ADDED: Mapzen geocoder. Contributed by migurski. (#183)

ADDED: GoogleV3 geocoder now supports a channel option. Contributed by gotche. (#206)

ADDED: Photon geocoder now accepts a new limit option. Contributed by Mariana Georgieva.

CHANGED: Use the IUGG mean earth radius for EARTH_RADIUS. Contributed by cffk. (#151)

CHANGED: Use the exact conversion factor from kilometers to miles. Contributed by cffk. (#150)

CHANGED: OpenMapQuest geocoder now properly supports api_key option and makes it required.

CHANGED: Photon geocoder: removed osm_tag option from reverse geocoding method, as Photon backend doesn't support it for reverse geocoding.

FIXED: Photon geocoder was always returning an empty address.

FIXED: Yandex geocoder was returning a truncated address (the name part of a place was missing).

FIXED: The custom User-Agent header was not actually sent. This also fixes broken Nominatim, which has recently banned the stock urllib user agent.

FIXED: geopy.util.get_version() function was throwing an ImportError exception instead of returning a version string.

FIXED: Docs for constructing a geopy.point.Point were referencing latitude and longitude in a wrong order. Contributed by micahcochran and sjorek. (#207 #229)

REMOVED: Navidata geocoder has been removed. Contributed by medecau. (#204)

Source code(tar.gz)
Source code(zip)
1.11.0(Mar 13, 2018)
ADDED: Photon geocoder. Contributed by mthh.

ADDED: Bing supports structured query parameters. Contributed by SemiNormal.

CHANGED: Geocoders send a User-Agent header, which by default is geopy/1.11.0. Configure it during geocoder initialization. Contributed by sebastianneubauer.

FIXED: Index out of range error with no results using Yandex. Contributed by facciocose.

FIXED: Nominatim was incorrectly sending view_box when not requested, and formatting it incorrectly. Contributed by m0zes.

Source code(tar.gz)
Source code(zip)
1.10.0(Apr 5, 2015)
CHANGED: GeocodeFarm now uses version 3 of the service's API, which allows use by unauthenticated users, multiple results, and SSL/TLS. You may need to obtain a new API key from GeocodeFarm, or use None for their free tier. Contributed by Eric Palakovich Carr.

ADDED: DataBC geocoder for use with the British Columbia government's DataBC service. Contributed by Benjamin Trigona-Harany.

ADDED: Placefinder's geocode method now requests a timezone if the with_timezone parameter is true. Contributed by willr.

FIXED: Nominatim specifies a viewbox parameter rather than the apparently deprecated view_box.

Source code(tar.gz)
Source code(zip)
1.9.1(Feb 17, 2015)
FIXED: Fix support for GoogleV3 bounds parameter. Contributed by Benjamin Trigona-Harany.

Source code(tar.gz)
Source code(zip)
1.9.0(Feb 12, 2015)
CHANGED: MapQuest geocoder removed as the API it uses is now only available to enterprise accounts. OpenMapQuest is a replacement for Nominatim-sourced data.

CHANGED: Nominatim now uses HTTPS by default and accepts a scheme argument. Contributed by srounet.

ADDED: Nominatim now accepts a domain argument, which allows using a different server than nominatim.openstreetmap.org. Contributed by srounet.

FIXED: Bing was not accessible from get_geocoder_for_service. Contributed by Adrián López.

Source code(tar.gz)
Source code(zip)
1.8.1(Jan 28, 2015)
FIXED: GoogleV3 geocoder did not send API keys for reverse and timezone methods.

Source code(tar.gz)
Source code(zip)
1.8.0(Jan 22, 2015)
ADDED: NaviData geocoder added. Contributed by NaviData.

CHANGED: LiveAddress now requires HTTPS connections. If you set scheme to be http, rather than the default https, you will now receive a ConfigurationError.

Source code(tar.gz)
Source code(zip)
1.7.1(Jan 6, 2015)
FIXED: IGN France geocoder's address formatting better handles results that do not have a building number. Contributed by Thomas Gratier.

Source code(tar.gz)
Source code(zip)
1.7.0(Dec 30, 2014)
ADDED: IGNFrance geocoder. Contributed by Thomas Gratier.

FIXED: Bing checks the response body for error codes.

Source code(tar.gz)
Source code(zip)
1.6.1(Dec 12, 2014)
FIXED: What3Words validation loosened. Contributed by spatialbitz.

FIXED: Point.format() includes altitude.

Source code(tar.gz)
Source code(zip)
1.6.0(Dec 9, 2014)
ADDED: Python 3.2 and PyPy3 compatibility. Contributed by Mike Toews.

Source code(tar.gz)
Source code(zip)
1.5.0(Dec 7, 2014)
ADDED: Yandex geocoder added. Contributed by htch.

ADDED: What3Words geocoder added. Contributed by spatialbitz.

FIXED: LiveAddress geocoder made compatible with a change in the service's authentication. An auth_id parameter was added to the geocoder's initialization. Contributed by Arsen Mamikonyan.

Source code(tar.gz)
Source code(zip)
1.4.0(Nov 8, 2014)
ADDED: Mapquest.reverse() method added. Contributed by Dody Suria Wijaya.

ADDED: Bing's geocoder now accepts the optional arguments "culture", "includeNeighborhood", and "include". Contributed by oskholl.

Source code(tar.gz)
Source code(zip)