opencage

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 on this page — 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

opencage on PyPI

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

Evidence: opencage-3.4.0-py3-none-any.whl

Keywords: geocoding, geocoder

Tags

More Utilities packages