---
id: opencage
version: "3.4.0"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# opencage — Wrapper module for the OpenCage Geocoder API

License: permissive · Maintenance: active · Downloads: 266.8K/mo

## What it is and what it does

opencage is a client library for the OpenCage Geocoding API, a web service that converts between addresses and geographic coordinates. It handles both forward geocoding (address → lat/long) and reverse geocoding (lat/long → address), and supports optional parameters like language preference and proximity hints to refine results.

The module offers both synchronous and asynchronous request methods, allowing you to make single queries or batch multiple requests efficiently. It wraps HTTP calls to the OpenCage API using Requests and aiohttp, handles authentication via API key, and raises specific exceptions (InvalidInputError, NotAuthorizedError, RateLimitExceededError, etc.) to help you diagnose problems. Context managers and async/await patterns are supported for connection reuse and parallel requests.

Use it for:

- Convert user-entered addresses into map coordinates for location-based applications or services
- Reverse-geocode GPS coordinates from mobile devices or sensors into human-readable street addresses
- Build batch geocoding pipelines that process thousands of addresses while reusing HTTP connections
- Implement location search features with proximity hints to disambiguate results in crowded areas
- Run parallel geocoding requests asynchronously to speed up large-scale data processing workflows

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A Python wrapper for the OpenCage Geocoding API that converts addresses to coordinates (forward geocoding) and coordinates to addresses (reverse geocoding), with support for both synchronous and asynchronous requests.

Yes. The package is actively maintained, has no known vulnerabilities, low installation friction, and a permissive license. It provides a straightforward, well-documented interface to a reliable geocoding service. Install it if you need to integrate address-to-coordinate or coordinate-to-address lookups into a Python application and are willing to obtain an OpenCage API key.

## Install

pip install opencage
uv add opencage
poetry add opencage

## Installing opencage

Before you install: Low friction installation with a pure-Python wheel. Actively maintained with a recent release (67 days ago) and steady repository activity. Depends on three well-established libraries: Requests, backoff, and aiohttp.

License in practice: Licensed under BSD-3-Clause (permissive), allowing commercial use, modification, and distribution with minimal restrictions beyond retaining the license notice.

Quickstart:

pip install opencage

from opencage.geocoder import OpenCageGeocode

geocoder = OpenCageGeocode('your-api-key')
results = geocoder.geocode('82 Clerkenwell Road, London')
print(results[0]['formatted'])

Requires a valid OpenCage Data API key (free tier available at opencagedata.com). Requires Python 3.9 or newer.

Verify before relying:

- Rate limits and quota details for the free vs. paid API tiers
- Performance characteristics when making large batches of requests
- Whether the module handles edge cases like ambiguous addresses or missing results gracefully

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 266.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

geocoding api wrapper, address to coordinates, reverse geocoding, latitude longitude lookup, forward geocoding python, address geocoder, async geocoding, geocoding, geolocation, async-support

[View on SkillFed](https://skillfed.io/packages/opencage) · [View on PyPI](https://pypi.org/project/opencage/)