# geopy > Python Geocoding Toolbox - **URL**: https://www.freshcrate.ai/projects/geopy - **Author**: Kostya Esmukov - **Category**: Frameworks - **Latest version**: `2.4.1` (2026-04-21) - **License**: MIT - **Source**: https://github.com/geopy/geopy/archive/2.4.1.tar.gz - **Homepage**: https://github.com/geopy/geopy - **Language**: Python - **GitHub**: 4,805 stars, 665 forks - **Registry**: pypi (`geopy`) - **Tags**: `distance`, `earth`, `geocode`, `geocoding`, `geographical`, `gis`, `maps`, `pypi` ## Description geopy ===== .. image:: https://img.shields.io/pypi/v/geopy.svg?style=flat-square :target: https://pypi.python.org/pypi/geopy/ :alt: Latest Version .. image:: https://img.shields.io/github/actions/workflow/status/geopy/geopy/ci.yml?branch=master&style=flat-square :target: https://github.com/geopy/geopy/actions/workflows/ci.yml?query=branch%3Amaster :alt: Build Status .. image:: https://img.shields.io/github/license/geopy/geopy.svg?style=flat-square :target: https://pypi.python.org/pypi/geopy/ :alt: License 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`_. .. _OpenStreetMap Nominatim: https://nominatim.org .. _Google Geocoding API (V3): https://developers.google.com/maps/documentation/geocoding/ .. _Geocoders doc section: https://geopy.readthedocs.io/en/latest/#geocoders .. _geopy.geocoders: https://github.com/geopy/geopy/tree/master/geopy/geocoders geopy is tested against CPython (versions 3.7, 3.8, 3.9, 3.10, 3.11, 3.12) and PyPy3. geopy 1.x line also supported CPython 2.7, 3.4 and PyPy2. © geopy contributors 2006-2018 (see AUTHORS) under the `MIT License `__. 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: .. code:: pycon >>> 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: .. code:: pycon >>> 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, taking pair of :code:`(lat, lon)` tuples: .. code:: pycon >>> 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, also taking pair of :code:`(lat, lon)` tuples: .. code:: pycon >>> 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 `__. ## Recent releases | Version | Date | Urgency | Changes | | --- | --- | --- | --- | | `2.4.1` | 2026-04-21 | Low | Imported from PyPI (2.4.1) | | `2.4.0` | 2023-08-27 | Low | ## 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_externa | | `2.3.0` | 2022-11-13 | Low | ## 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` | | `2.2.0` | 2021-07-11 | Low | ## 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 inste | | `2.1.0` | 2020-12-27 | Low | ## 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 Ma | | `2.0.0` | 2020-06-27 | Low | 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 | | `1.23.0` | 2020-06-27 | Low | 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 | | `2.0.0rc1` | 2020-06-21 | Low | 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 | | `1.22.0` | 2020-05-11 | Low | * 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 whic | | `1.21.0` | 2020-02-02 | Low | * 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) * | ## Citation - HTML: https://www.freshcrate.ai/projects/geopy - Markdown: https://www.freshcrate.ai/projects/geopy.md - Dependencies JSON: https://www.freshcrate.ai/api/projects/geopy/deps _Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._