opencage

library3.4.0pypypi✓ verified 84d ago

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.

http-networking data

pip install opencage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPENCAGE

opencage

http-networkingpythonv3.4.0

Install

4.5s avg

Import

999ms

Disk

29MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.054s · 29.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.5s · import 0.944s · 32MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Geocoder

✓ from opencage.geocoder import OpenCageGeocode

✗ from opencage import Geocoder

Direct import is non-existent; must use OpenCageGeocode class

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')

Debug

Known issues

breakingIn 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']

affects: < 2.2.4

gotchaAPI 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.

affects: all

deprecatedThe '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`

affects: >= 3.0.0

Errors

Common errors & fixes

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

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')`

ModuleNotFoundError: No module named 'opencage'

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

fix

Install with `pip install opencage` and import from `opencage.geocoder`

KeyError: 'lat'

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']

Upgrade

Version history

3.4.0latest on PyPI · released Jun 8, 2026

Audit

Dependencies

requestsrequiredHTTP requests to OpenCage API

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/OpenCageData/python-opencage-geocoder ↗

packagehttps://pypi.org/project/opencage/ ↗

homepagehttps://opencagedata.com ↗