OpenCage Getting Started: Geocoding API Integration (2026)

Getting started overview

Integrating with the OpenCage Geocoding API involves a few core steps: account creation, API key generation, and executing a basic geocoding request. OpenCage provides both forward geocoding (converting addresses to coordinates) and reverse geocoding (converting coordinates to addresses) capabilities via a JSON API. The service is built on open data, primarily OpenStreetMap data, which contributes to its global coverage and data transparency.

Developers can interact with the API directly via HTTP requests or utilize one of the available client libraries for languages such as Python, Node.js, and PHP. This guide focuses on the fundamental steps to ensure a working integration.

Here's a quick reference for the initial setup:

Create an account and get keys

To access the OpenCage Geocoding API, you must first create an account on the official OpenCage website. This process establishes your user profile and grants you access to your API key, which is essential for authenticating all requests.

1. Navigate to the OpenCage Website: Go to the OpenCage homepage.
2. Sign Up: Look for a "Sign Up" or "Get Started" button, typically located in the navigation bar or prominent on the landing page.
3. Provide Details: Complete the registration form with your email address and a strong password. You may need to confirm your email address through a verification link sent to your inbox.
4. Access Dashboard: Once registered and logged in, you will be directed to your OpenCage dashboard.
5. Locate API Key: Your API key should be visible on your dashboard, often labeled as "Your API Key" or similar. Copy this key, as it will be used in all your API calls. OpenCage offers a free tier with 2,500 requests per day, which is automatically assigned upon signup.

It is recommended to store your API key securely and avoid hardcoding it directly into client-side applications or publicly accessible code repositories. For server-side applications, use environment variables or a secrets management service.

Your first request

After obtaining your API key, you can make your first geocoding request. This example uses a simple HTTP GET request to perform forward geocoding, converting an address into geographic coordinates.

API Endpoint

The primary endpoint for geocoding requests is https://api.opencagedata.com/geocode/v1/json.

Request Parameters

• q: The query string (e.g., address, city, landmark).
• key: Your OpenCage API key.

Example Request (Forward Geocoding)

Let's find the coordinates for "Paris, France". Replace YOUR_API_KEY with your actual key.

curl "https://api.opencagedata.com/geocode/v1/json?q=Paris%2C%20France&key=YOUR_API_KEY"

Example Response Structure

A successful response will return a JSON object containing geocoding results. The exact structure can be complex, but key information is typically found within the results array.

{
  "results": [
    {
      "annotations": { ... },
      "bounds": { ... },
      "components": { ... },
      "confidence": 8,
      "formatted": "Paris, France",
      "geometry": {
        "lat": 48.8566101,
        "lng": 2.3522219
      },
      "timestamp": { ... }
    }
  ],
  "status": {
    "code": 200,
    "message": "OK"
  },
  "stay_informed": { ... },
  "thanks": "For using OpenCage Geocoder",
  "total_results": 1
}

In this example, the latitude (lat) and longitude (lng) for Paris are found in the geometry object within the first result.

Reverse Geocoding Example

To perform reverse geocoding (converting coordinates to an address), you would structure the q parameter as latitude,longitude:

curl "https://api.opencagedata.com/geocode/v1/json?q=48.8566%2C2.3522&key=YOUR_API_KEY"

Common next steps

Once you have successfully made your first request, consider these common next steps to further integrate OpenCage into your application:

1. Explore API Parameters: The OpenCage API offers various parameters to refine your queries, such as language preferences (language), country filtering (countrycode), and result biasing (bounds, proximity). Experiment with these to get more precise and relevant results for your specific use case.
2. Integrate an SDK: For easier development, consider using one of the official or community-maintained SDKs. These libraries abstract away the HTTP request details and provide language-specific methods for interacting with the API. For example, the Python SDK simplifies API calls into function calls.
3. Error Handling: Implement robust error handling in your application. The API returns specific status codes and messages for various issues, such as invalid API keys, rate limit exceeded, or no results found. Proper error handling ensures your application can gracefully manage unexpected responses.
4. Rate Limit Management: Be aware of the rate limits associated with your OpenCage plan. The free tier allows 2,500 requests per day. For higher volumes, you may need to upgrade to a paid plan. Implement client-side logic to respect these limits, potentially using exponential backoff for retries.
5. Asynchronous Requests: For applications requiring high throughput or responsive user interfaces, consider making API requests asynchronously to avoid blocking the main thread.
6. Caching: If your application frequently requests the same geocoding data, implement a caching mechanism to store results locally. This can reduce API calls and improve performance, while also helping you stay within your rate limits.
7. Security Best Practices: Always keep your API key confidential. For web applications, avoid exposing the key directly in client-side JavaScript. Instead, route requests through a secure backend server where the API key can be managed as an environment variable or through a secrets manager. This aligns with general API key security best practices.

Troubleshooting the first call

When encountering issues with your initial OpenCage API request, consider the following common problems and solutions:

• Invalid API Key:
  • Issue: The most frequent cause of errors. The API key might be incorrect, expired, or have leading/trailing spaces.
  • Solution: Double-check your API key against the one displayed on your OpenCage dashboard. Ensure no extra characters are included.
• Rate Limit Exceeded (Status Code 429):
  • Issue: You have sent too many requests within a given time frame, exceeding your plan's limits.
  • Solution: Wait for the rate limit window to reset. For higher volumes, consider upgrading your OpenCage subscription plan. Implement client-side logic to track and manage your request frequency.
• Missing or Invalid Query Parameter (Status Code 400):
  • Issue: The q parameter (for query string) or key parameter is missing or malformed in your request URL.
  • Solution: Verify that your URL includes both q=your_query and key=YOUR_API_KEY, and that the values are correctly URL-encoded (e.g., spaces replaced with %20). Refer to the OpenCage API reference for required parameters.
• Network Connectivity Issues:
  • Issue: Your application or environment cannot reach the OpenCage API servers.
  • Solution: Check your internet connection. If you are behind a firewall or proxy, ensure that access to api.opencagedata.com is permitted.
• No Results Found (Status Code 200, but empty results array):
  • Issue: The API successfully processed your request, but could not find a match for your query.
  • Solution: Review your query string for typos or ambiguities. Try making the query more specific (e.g., including a city or country).
• Incorrect Endpoint:
  • Issue: You might be using an outdated or incorrect API endpoint URL.
  • Solution: Confirm that you are using the correct endpoint: https://api.opencagedata.com/geocode/v1/json.
• CORS Issues (for browser-based requests):
  • Issue: If making requests directly from a web browser (not recommended for API key security), you might encounter Cross-Origin Resource Sharing errors.
  • Solution: OpenCage has CORS enabled for browser-based requests, but you should generally proxy API calls through your own backend to protect your API key.