OpenCage Geocoding Module for Python

A Python module to access the OpenCage Geocoder.

Build Status / Code Quality / etc

Usage

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')
print(result[0]['formatted'])
# 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)

Exceptions

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.