Opencagedata OpenCage Geocoder
Official vendor OpenAPI document · agent-readyMaps GeolocationGeocodingapiKey3 EndpointsREST
For Agents
Geocode addresses to coordinates and reverse-geocode coordinates to formatted addresses worldwide using open data, with JSON, XML, or GeoJSON output.
Use for: Geocode the address '5 Rue de Rivoli Paris' to coordinates, Reverse geocode latitude 51.5074 longitude -0.1278 to a formatted address, Find the country and ISO code for a given city name, Get coordinates for a postal address as GeoJSON for a map layer
Not supported: Does not handle routing, places search, or map tile rendering - use for forward and reverse geocoding only.
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.
Install Jentic One Beta
Connect the OpenCage Geocoder to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the OpenCage Geocoder, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fopencagedata.com%2Fopencagedata" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fopencagedata.com%2Fopencagedata" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with OpenCage Geocoder API.
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
Patterns agents use OpenCage Geocoder API for, with concrete tasks.
★ 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.
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.
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.
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.
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
3 endpoints — opencage geocoder is a worldwide forward and reverse geocoding api built on open data sources including openstreetmap, natural earth, and government-published gazetteers.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
Alternative
Positionstack API
Forward and reverse geocoder built on open data with similar global coverage.
Choose Positionstack when you need a near drop-in alternative or want to compare confidence scores between two open-data providers.
FAQs
Specific to using OpenCage Geocoder API through Jentic.
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.
GET STARTED