A Python module to access the OpenCage Geocoding API.
You can find a comprehensive tutorial for using this module on the OpenCage site.
There are two brief video tutorials on YouTube, one covering forward geocoding, one covering reverse geocoding.
There is an Agent Skill for working with the OpenCage Geocoding API which includes a reference file for developing in Python using this module.
Supports Python 3.9 or newer. Starting opencage version 3.0 depends on asyncio package.
Install the module:
pip install opencageLoad the module:
from opencage.geocoder import OpenCageGeocodeCreate 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' geocode method:
query = '82 Clerkenwell Road, London'
results = geocoder.geocode(query)You can add additional parameters:
results = geocoder.geocode('London', no_annotations=1, language='es')For example you can use the proximity parameter to provide the geocoder with a hint:
results = geocoder.geocode('London', proximity='42.828576, -81.406643')
print(results[0]['formatted'])
# u'London, ON N6A 3M8, Canada'Turn a lat/long into an address with the reverse_geocode method:
result = 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]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.8 and the asyncio and aiohttp packages installed.
async with OpenCageGeocode(key) as geocoder:
results = await geocoder.geocode_async(address)If you have trouble accesing the OpenCage API with https, e.g. issues with OpenSSL libraries in your enviroment, then you can set the 'http' protocol instead. Please understand that the connection to the OpenCage API will no longer be encrypted.
geocoder = OpenCageGeocode('your-api-key', 'http')If anything goes wrong, then an exception will be raised:
InvalidInputErrorfor non-unicode query stringsNotAuthorizedErrorif API key is missing, invalid syntax or disabledForbiddenErrorAPI key is blocked or suspendedRateLimitExceededErrorif you go past your rate limitUnknownErrorif there's some problem with the API (bad results, 500 status code, etc)
The opencage CLI now lives in its own package. See opencage-cli — install with pip install opencage-cli.
This software is copyright OpenCage GmbH.
Please see LICENSE.txt
We run a worldwide geocoding API and geosearch service based on open data. 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.