OpenCage Geocoder

3.3.1 verified Mon Apr 27 auth: no python

Python wrapper for the OpenCage Geocoder API. Provides forward and reverse geocoding, timezone lookups, and formatted output. Current version: 3.3.1, supports Python >=3.9, maintained actively.

pip install opencage

Common errors

error opencage.geocoder.OpenCageGeocode.__init__() got an unexpected keyword argument 'api_key' ↓

cause Trying to pass API key as keyword instead of positional argument

fix

Use OpenCageGeocode('your-api-key') instead of OpenCageGeocode(api_key='your-api-key')

error ModuleNotFoundError: No module named 'opencage' ↓

cause Library not installed or installed under different name (e.g., opencage-geocoder)

fix

Install with pip install opencage and import from opencage.geocoder

error KeyError: 'lat' ↓

cause Using old response format expecting 'lat' at top level; now inside 'geometry'

fix

Access coordinates via result[0]['geometry']['lat'] and result[0]['geometry']['lng']

Warnings

breaking In version 2.2.4, the API response format changed: 'lat' and 'lng' keys were moved inside 'geometry'. Old code accessing result[0]['lat'] will break. ↓

fix Access coordinates via result[0]['geometry']['lat'] and result[0]['geometry']['lng']

gotcha API key must be passed as first positional argument, not as keyword. Using `OpenCageGeocode(api_key=...)` will raise an unexpected keyword argument error. ↓

fix Use `OpenCageGeocode(key)` where key is the API key string.

deprecated The 'Geocoder' class alias in opencage.geocoder was deprecated in 2.2.0 and removed in 3.0.0. Use 'OpenCageGeocode' instead. ↓

fix Replace `from opencage.geocoder import Geocoder` with `from opencage.geocoder import OpenCageGeocode`

Imports

Geocoder
wrong
```
from opencage import Geocoder
```
correct
```
from opencage.geocoder import OpenCageGeocode
```
Direct import is non-existent; must use OpenCageGeocode class

Quickstart

Initialize with API key and geocode an address.

from opencage.geocoder import OpenCageGeocode
import os

key = os.environ.get('OPENCAGE_API_KEY', 'YOUR-API-KEY')
g = OpenCageGeocode(key)
result = g.geocode('London')
print(result[0]['geometry'] if result else 'No results')