The OpenCage geocoding API supports forward and reverse geocoding for the entire world and is based on various open datasources like OpenStreetMap.

Programming language: Python
License: BSD 3-clause "New" or "Revised" License
Tags: Scientific     Engineering     Utilities     GIS     Geocoding     OpenCage     Opendata    
Latest version: v1.2.1


OpenCage Geocoding Module for Python

A Python module to access the OpenCage Geocoder.

Build Status / Code Quality / etc

Build Status Kritika Analysis Status PyPI version


Install the module:

pip install opencage

Load the module:

from opencage.geocoder import OpenCageGeocode

Create an instance of the geocoder module, passing a valid OpenCage Data Geocoder API key as a parameter to the geocoder modules's constructor:

key = 'your-api-key-here'
geocoder = OpenCageGeocode(key)

Pass a string containing the query or address to be geocoded to the modules's geocode method:

query = "82 Clerkenwell Road, London"
result = geocoder.geocode(query)

You can add additional parameters:

result = geocoder.geocode('London', no_annotations=1, language='es')

You can use the proximity parameter to provide the geocoder with a hint:

result = geocoder.geocode('London', proximity='42.828576, -81.406643')
# u'London, ON N6A 3M8, Canada'

Reverse geocoding

Turn a lat/long into an address with the reverse_geocode method:

results = geocoder.reverse_geocode(51.51024, -0.10303)


If anything goes wrong, then an exception will be raised:

  • InvalidInputError for non-unicode query strings
  • UnknownError if there's some problem with the API (bad results, 500 status code, etc)
  • RateLimitExceededError if you go past your rate limit

Copyright & Licencse

This software is copyright OpenCage GmbH. Please see LICENSE.txt

Who is OpenCage GmbH?

We run the OpenCage Geocoder. Learn more about us.

We also run Geomob, a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy the Geomob podcast.

*Note that all licence references and agreements mentioned in the OpenCage Data Geocoding Module for Python README section above are relevant to that project's source code only.