canonical: https://jentic.com/apis/opencagedata.com/opencagedata

# Opencagedata OpenCage Geocoder

OpenCage Geocoder is a worldwide forward and reverse geocoding API built on open data sources including OpenStreetMap, Natural Earth, and government-published gazetteers. It converts free-form place names and structured addresses into latitude and longitude coordinates, and reverses coordinates back into formatted addresses with administrative hierarchy and country codes. Responses are returned in JSON, XML, or GeoJSON to suit different mapping stacks. Subscription customers receive responses without the rate element or X-Ratelimit headers because they are not subject to hard daily caps.

## For AI agents

Geocode addresses to coordinates and reverse-geocode coordinates to formatted addresses worldwide using open data, with JSON, XML, or GeoJSON output.

## Scope

Does not handle routing, places search, or map tile rendering - use for forward and reverse geocoding only.

## Capabilities

- Forward geocode a free-form address string into latitude and longitude with confidence scoring
- Reverse geocode a latitude/longitude pair into a formatted address with administrative hierarchy
- Bias geocoding results toward a specific country code, bounding box, or proximity point
- Filter responses by language using the IETF BCP 47 language tag for localised place names
- Return results as GeoJSON FeatureCollection for direct rendering on Leaflet or Mapbox layers
- Inspect remaining daily quota via the rate element returned on free-tier responses

## Use cases

### Address to Coordinates Conversion

Convert user-entered addresses into latitude and longitude for storage, mapping, or distance calculations. The /json endpoint accepts a q query string and returns ranked candidates with confidence, formatted address, and a components block covering country, state, city, postcode, and road. This suits signup flows, delivery interfaces, and CRM enrichment pipelines that need accurate placement.

Example prompt: GET /json?q=10+Downing+Street+London&key=YOUR_KEY and return the lat/lng and components.country_code from the first result.

### Reverse Geocoding for Field Apps

Translate device GPS coordinates into a human-readable address for field-service, ride-hail, and delivery apps. Send the lat,lng pair to /json or /geojson and OpenCage returns a formatted address plus an annotations block with timezone, currency, and what3words tokens, removing the need to stitch together multiple gazetteer lookups.

Example prompt: GET /json?q=51.952659,7.632473&key=YOUR_KEY and return the formatted field plus the annotations.timezone.name.

### GeoJSON Map Overlays

Generate GeoJSON FeatureCollections directly from address inputs to drive Leaflet or Mapbox overlays without a client-side conversion step. The /geojson endpoint returns the same geocoding data as /json but already wrapped in the GeoJSON shape, which fits cleanly into mapping libraries that expect Feature inputs.

Example prompt: GET /geojson?q=Eiffel+Tower&key=YOUR_KEY and pass the resulting FeatureCollection to L.geoJSON() to render a marker.

### AI Agent Location Enrichment

Through Jentic, an AI agent enriches contact, order, or event records with coordinates and structured location components in a single search-load-execute cycle. This suits CRM agents that need to plot customers on a map, logistics agents that need to validate delivery addresses, and analytics agents that need to bucket records by region.

Example prompt: Through Jentic, search for 'geocode an address', load GET /json, and execute it with q='Brandenburger Tor Berlin' to return lat, lng, and country code.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /json | Forward or reverse geocode and return JSON |
| GET | /xml | Forward or reverse geocode and return XML |
| GET | /geojson | Forward or reverse geocode and return GeoJSON |

## Key resources

- **JSON Geocoding** — Forward and reverse geocoding with structured JSON output
- **XML Geocoding** — Same geocoding data returned as XML for legacy clients
- **GeoJSON Geocoding** — Geocoding output wrapped as a GeoJSON FeatureCollection

## Why Jentic

- **Setup:** Wiring OpenCage by hand means managing the API key, appending it to the 'key' query parameter on every request, and picking the right JSON, XML, or GeoJSON response format yourself. Through Jentic you install once, import the OpenCage Geocoder from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** OpenCage is a read-only geocoding API whose query travels in the request parameters, so scope it by limiting the agent to the operations it needs, such as the JSON or GeoJSON geocoding call. You choose the operations it may call, and nothing beyond that set runs.
- **Credential handling:** Your OpenCage API key is stored once, encrypted, by your own Jentic One instance and injected into the 'key' query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'geocode an address' or 'reverse geocode coordinates', and Jentic returns the matching /json, /xml, or /geojson operation with its q parameter schema so the agent calls the right endpoint without browsing the OpenCage docs.

## Related APIs

- **Geocodio API** — US and Canada-focused geocoder with bulk processing.
- **Positionstack API** — Forward and reverse geocoder built on open data with similar global coverage.
- **HERE Maps API** — Routing, traffic, and places that pair with geocoded coordinates.
- **TomTom API** — Routing and traffic data for the resolved coordinates.

## FAQ

### What authentication does the OpenCage Geocoder use?

The API uses an API key passed as the key query parameter on every request - the spec defines this as the ApiKeyAuth security scheme with location 'query'. Through Jentic, the key is stored encrypted in your Jentic One instance and injected into the URL at execution time, so the agent never sees the raw key value.

### Can I reverse geocode a latitude and longitude with this API?

Yes. Pass the coordinates as a comma-separated string in the q parameter (for example q=51.5074,-0.1278) on /json, /xml, or /geojson. OpenCage returns a formatted address, structured components, and an annotations block with extras such as timezone and what3words tokens.

### What are the rate limits for the OpenCage Geocoder?

Free trial accounts are capped at one request per second and 2,500 requests per day, with the remaining quota reported in the response 'rate' element and X-Ratelimit headers. Paid subscription tiers remove the daily cap and the rate element is omitted from those responses, as called out in the spec description.

### How do I geocode an address through Jentic?

Search Jentic for 'geocode an address', load GET /json, and execute it with q set to the address string. Jentic injects the API key from your Jentic One instance and returns the parsed response, so an agent can extract results[0].geometry.lat and results[0].geometry.lng without writing HTTP client code.

### Is the OpenCage Geocoder free?

OpenCage offers a free trial tier of 2,500 requests per day at 1 request per second, suitable for development and small-scale apps. Production volumes require a paid subscription - pricing scales with daily request volume and is published on opencagedata.com.

### Does OpenCage support GeoJSON output for map libraries?

Yes. The dedicated /geojson endpoint returns a GeoJSON FeatureCollection with the same geocoding payload, which can be passed directly to Leaflet's L.geoJSON or Mapbox GL JS source definitions without an intermediate conversion step.

### Can I limit what my agent is allowed to do with the OpenCage Geocoder API?

Yes. Because you self-host Jentic One, your own rules decide which OpenCage operations the agent may call and which credential it uses. OpenCage is a read-only geocoding API, so you can restrict the agent to just the operations it needs, such as the /json forward and reverse geocoding call while withholding the /xml or /geojson endpoints. Nothing beyond the operation set you approve ever runs, and your API key is injected only at execution time.