index.rst

Welcome to GeoPy's documentation!

Documentation

https://geopy.readthedocs.io/

Source Code

https://github.com/geopy/geopy

Stack Overflow

https://stackoverflow.com/questions/tagged/geopy

GIS Stack Exchange

https://gis.stackexchange.com/questions/tagged/geopy

Discussions

https://github.com/geopy/geopy/discussions

Issue Tracker

https://github.com/geopy/geopy/issues

PyPI

https://pypi.org/project/geopy/

geopy

index

Installation

pip install geopy

Geocoders

geopy.geocoders

Accessing Geocoders

The typical way of retrieving a geocoder class is to make an import from geopy.geocoders package:

from geopy.geocoders import Nominatim

geopy.geocoders.get_geocoder_for_service

Default Options Object

geopy.geocoders.options

Usage with Pandas

It is possible to geocode a pandas DataFrame with geopy, however, rate-limiting must be taken into account.

A large number of DataFrame rows might produce a significant amount of geocoding requests to a Geocoding service, which might be throttled by the service (e.g. by returning Too Many Requests 429 HTTP error or timing out).

geopy.extra.rate_limiter classes provide a convenient wrapper, which can be used to automatically add delays between geocoding calls to reduce the load on the Geocoding service. Also it can retry failed requests and swallow errors for individual rows.

If you're having the Too Many Requests error, you may try the following:

• Use geopy.extra.rate_limiter with non-zero min_delay_seconds.
• Try a different Geocoding service (please consult with their ToS first, as some services prohibit bulk geocoding).
• Take a paid plan on the chosen Geocoding service, which provides higher quota.
• Provision your own local copy of the Geocoding service (such as Nominatim).

Rate Limiter

geopy.extra.rate_limiter

geopy.extra.rate_limiter.RateLimiter

__init__

geopy.extra.rate_limiter.AsyncRateLimiter

__init__

ArcGIS

geopy.geocoders.ArcGIS

__init__

AzureMaps

geopy.geocoders.AzureMaps

__init__

Baidu

geopy.geocoders.Baidu

__init__

BaiduV3

geopy.geocoders.BaiduV3

__init__

BANFrance

geopy.geocoders.BANFrance

__init__

Bing

geopy.geocoders.Bing

__init__

DataBC

geopy.geocoders.DataBC

__init__

GeocodeEarth

geopy.geocoders.GeocodeEarth

__init__

GeocodeFarm

2.2 This class has been removed, because the service is too unreliable. See 445.

Geocodio

geopy.geocoders.Geocodio

__init__

Geokeo

geopy.geocoders.Geokeo

__init__

Geolake

geopy.geocoders.Geolake

__init__

GeoNames

geopy.geocoders.GeoNames

__init__

GoogleV3

geopy.geocoders.GoogleV3

__init__

HERE

geopy.geocoders.Here

__init__

HEREv7

geopy.geocoders.HereV7

__init__

IGNFrance

geopy.geocoders.IGNFrance

__init__

MapBox

geopy.geocoders.MapBox

__init__

MapQuest

geopy.geocoders.MapQuest

__init__

MapTiler

geopy.geocoders.MapTiler

__init__

OpenCage

geopy.geocoders.OpenCage

__init__

OpenMapQuest

geopy.geocoders.OpenMapQuest

__init__

Nominatim

geopy.geocoders.Nominatim

__init__

Pelias

geopy.geocoders.Pelias

__init__

Photon

geopy.geocoders.Photon

__init__

PickPoint

geopy.geocoders.PickPoint

__init__

LiveAddress

geopy.geocoders.LiveAddress

__init__

TomTom

geopy.geocoders.TomTom

__init__

What3Words

geopy.geocoders.What3Words

__init__

What3WordsV3

geopy.geocoders.What3WordsV3

__init__

Woosmap

geopy.geocoders.Woosmap

__init__

Yandex

geopy.geocoders.Yandex

__init__

Calculating Distance

geopy.distance

geopy.distance.lonlat

geopy.distance.Distance

geopy.distance.geodesic

geopy.distance.great_circle

Data

geopy.location.Location

geopy.point.Point

__new__

geopy.timezone.Timezone

Units Conversion

geopy.units

Exceptions

geopy.exc.GeopyError

geopy.exc.ConfigurationError

geopy.exc.GeocoderServiceError

geopy.exc.GeocoderQueryError

geopy.exc.GeocoderQuotaExceeded

geopy.exc.GeocoderRateLimited

geopy.exc.GeocoderAuthenticationFailure

geopy.exc.GeocoderInsufficientPrivileges

geopy.exc.GeocoderTimedOut

geopy.exc.GeocoderUnavailable

geopy.exc.GeocoderParseError

geopy.exc.GeocoderNotFound

Adapters

geopy.adapters

Supported Adapters

geopy.adapters.RequestsAdapter

geopy.adapters.URLLibAdapter

geopy.adapters.AioHTTPAdapter

Base Classes

geopy.adapters.AdapterHTTPError

__init__

geopy.adapters.BaseAdapter

__init__

geopy.adapters.BaseSyncAdapter

geopy.adapters.BaseAsyncAdapter

Logging

geopy will log geocoding URLs with a logger name geopy at level DEBUG, and for some geocoders, these URLs will include authentication information.

HTTP bodies of responses with unsuccessful status codes are logged with INFO level.

Default logging level is NOTSET, which delegates the messages processing to the root logger. See docs for logging.Logger.setLevel for more information.

Semver

geopy attempts to follow semantic versioning, however some breaking changes are still being made in minor releases, such as:

• Backwards-incompatible changes of the undocumented API. This shouldn't affect anyone, unless they extend geocoder classes or use undocumented features or monkey-patch anything. If you believe that something is missing in geopy, please consider opening an issue or providing a patch/PR instead of hacking around geopy.
• Geocoding services sometimes introduce new APIs and deprecate the previous ones. We try to upgrade without breaking the geocoder's API interface, but the geopy.location.Location.raw value might change in a backwards-incompatible way.
• Behavior for invalid input and peculiar edge cases might be altered. For example, geopy.point.Point instances previously did coordinate values normalization, though it's not documented, and it was completely wrong for the latitudes outside the [-90; 90] range. So instead of using an incorrectly normalized value for latitude, a ValueError exception is now thrown (294).

Features and usages being phased out are covered with deprecation warnings when possible. Make sure to run your python with the -Wd switch to see if your code emits the warnings.

To make the upgrade less painful, please read the changelog before upgrading.

Changelog

Changelog for 2.x.x series <changelog_2xx>.

Changelog for 1.x.x series <changelog_1xx>.

Changelog for 0.9x series <changelog_09x>.

Indices and search

• genindex
• search