Skip to main content

Wrapper module for the OpenCage Geocoder API

Project description

OpenCage Geocoding Module for Python

A Python module to access the OpenCage Geocoder.

Build Status / Code Quality / etc

PyPI version Downloads Versions GitHub contributors Build Status Twitter Follow


Supports Python 3.6 or newer. Use the older opencage 1.x releases if you need Python 2.7 support.

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)


You can reuse your HTTP connection for multiple requests by using a with block. This can help performance when making a lot of requests:

queries = ['82 Clerkenwell Road, London', ...]
with OpenCageGeocode(key) as geocoder:
    # Queries reuse the same HTTP connection
    results = [geocoder.geocode(query) for query in queries]

Asycronous requests

You can run requests in parallel with the geocode_async and reverse_geocode_async method which have the same parameters and response as their synronous counterparts. You will need at least Python 3.7 and the asyncio and aiohttp packages installed.

async with OpenCageGeocode(key) as geocoder:
    results = await geocoder.geocode_async(address)

For a more complete example and links to futher tutorials on asycronous IO see in the examples directory.


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 & License

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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

opencage-2.0.0.tar.gz (9.7 kB view hashes)

Uploaded source

Built Distribution

opencage-2.0.0-py3-none-any.whl (13.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page