# Opencage

OpenCage Geocoder provides a simple API for forward and reverse geocoding using open data sources.

- **Category:** developer tools
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 7
- **Triggers:** 0
- **Slug:** `OPENCAGE`
- **Version:** 20260223_00

## Tools

### Forward Geocode Address

**Slug:** `OPENCAGE_GEOCODE_FORWARD`

Tool to convert a human-readable address into geographic coordinates. Use when you need to retrieve latitude and longitude from an address.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | The address or free-form query to geocode |
| `abbrv` | integer | No | Return abbreviated results (0=false,1=true) |
| `limit` | integer | No | Maximum number of results (1-100) |
| `bounds` | string | No | Bias results to bounding box: west,south,east,north |
| `pretty` | boolean | No | Format the JSON response for readability |
| `language` | string | No | Preferred language for results (ISO 639-1 code) |
| `proximity` | string | No | Bias results near a point: latitude,longitude |
| `add_request` | integer | No | Include original request in response (0=false,1=true) |
| `countrycode` | string | No | Restrict to country codes (comma-separated ISO 3166-1 alpha-2) |
| `min_confidence` | integer | No | Minimum confidence score (1-10) |
| `no_annotations` | boolean | No | Exclude supplementary information in results |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Geocode to GeoJSON

**Slug:** `OPENCAGE_GEOCODE_GEOJSON`

Geocode addresses or coordinates and return results in GeoJSON FeatureCollection format. Use this tool when you need: - Geographic data in standard GeoJSON format for mapping applications - Forward geocoding: convert addresses to coordinates - Reverse geocoding: convert coordinates to addresses The response includes coordinates, formatted addresses, and optional annotations like timezone, currency, and sun times for each location.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Query string: either an address/placename for forward geocoding, or 'lat,lng' coordinates for reverse geocoding. |
| `abbrv` | integer | No | Use abbreviated address fields: 1 to enable, 0 to disable. |
| `limit` | integer | No | Maximum number of results to return (1-100). Default is 10. |
| `bounds` | string | No | Restrict results to bounding box as 'min_lng,min_lat,max_lng,max_lat'. |
| `pretty` | boolean | No | Pretty-print the JSON response for readability. |
| `language` | string | No | Preferred response language as IETF language tag (e.g., 'en', 'de', 'fr'). |
| `roadinfo` | boolean | No | Include detailed road/driving information in annotations. |
| `proximity` | string | No | Bias results toward a location as 'lat,lng' (e.g., '52.5200,13.4050'). |
| `add_request` | boolean | No | Include original request parameters in the response. |
| `countrycode` | string | No | Restrict results to specific countries. Comma-separated ISO 3166-1 alpha-2 codes (e.g., 'us', 'de,fr'). |
| `address_only` | boolean | No | Return only address-type results (exclude POIs, landmarks). |
| `min_confidence` | integer | No | Minimum confidence level for results (1-10). Only results with confidence >= this value are returned. |
| `no_annotations` | boolean | No | Exclude detailed annotations (timezone, currency, sun times, etc.) from response. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Geocode with JSONP

**Slug:** `OPENCAGE_GEOCODE_GEOJSONP`

Geocode an address and return results wrapped in a JavaScript callback function (JSONP format). Use this tool when you need geocoding results that can be directly consumed by JavaScript through a callback function, typically for cross-domain AJAX requests in browser environments. The response wraps standard geocoding JSON with your specified callback function name. Example response: myCallback({"results":[{"geometry":{"lat":52.5,"lng":13.4},"formatted":"Berlin, Germany",...}],...})

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | The address or location query to geocode (e.g., 'Berlin, Germany' or '1600 Pennsylvania Ave, Washington DC') |
| `abbrv` | integer | No | Abbreviate place names in results. Set to 1 to abbreviate (e.g., 'NYC' instead of 'New York City'), 0 for full names. |
| `limit` | integer | No | Maximum number of results to return (1-100). Defaults to 10 if not specified. |
| `bounds` | string | No | Restrict results to a geographic bounding box, specified as 'minLng,minLat,maxLng,maxLat' (west,south,east,north). Example: '-0.563,51.280,0.278,51.686' for Greater London. |
| `pretty` | integer | No | Format JSON output with indentation for readability. Set to 1 to enable. For debugging only. |
| `callback` | string | Yes | Name of the JavaScript callback function to wrap the response (e.g., 'handleGeocode') |
| `language` | string | No | Preferred language for results using ISO 639-1 language code (e.g., 'en' for English, 'de' for German). |
| `no_dedupe` | integer | No | Disable automatic deduplication of results. Set to 1 to include potential duplicates. |
| `no_record` | integer | No | Do not log this request in your account history. Set to 1 to disable logging. |
| `proximity` | string | No | Bias results towards a specific location, specified as 'lat,lng'. Example: '51.952,-1.162' for near Oxford, UK. |
| `add_request` | integer | No | Include the original request parameters in the response. Set to 1 to include. |
| `countrycode` | string | No | Limit results to a specific country using ISO 3166-1 alpha-2 country code (e.g., 'US', 'DE', 'GB'). |
| `min_confidence` | integer | No | Minimum confidence score (0-10) for results. Higher values return more precise matches only. |
| `no_annotations` | integer | No | Exclude supplementary annotations (timezone, currency, etc.) from results. Set to 1 to exclude. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Geocode Google v3 JSON

**Slug:** `OPENCAGE_GEOCODE_GOOGLE_V3_JSON`

Tool to perform forward geocoding and return results in Google Geocoding API v3 compatible JSON format. Use when you need Google v3 compatible output for legacy integrations. Note: This is a legacy format that may be discontinued; using the standard JSON format is recommended.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | The query string to be geocoded. Either latitude,longitude for reverse geocoding or a placename/address for forward geocoding. Must be URL encoded. |
| `abbrv` | integer ("0" | "1") | No | When set to 1, attempt to abbreviate and shorten the formatted string returned |
| `limit` | integer | No | Maximum number of results to return. Default is 10, max is 100. Only applies to forward geocoding. |
| `bounds` | string | No | Restrict forward geocoding results to a bounding box. Format: min_lng,min_lat,max_lng,max_lat |
| `pretty` | integer ("0" | "1") | No | When set to 1, results are pretty printed for easier reading |
| `language` | string | No | IETF format language code (e.g., es, pt-BR) or 'native' for local language(s) |
| `roadinfo` | integer ("0" | "1") | No | When set to 1, attempt to match the nearest road and fill additional roadinfo annotation |
| `no_dedupe` | integer ("0" | "1") | No | When set to 1, results will not be deduplicated |
| `no_record` | integer ("0" | "1") | No | When set to 1, the query contents are not logged for privacy |
| `proximity` | string | No | Bias forward geocoding results towards a location. Format: latitude,longitude |
| `add_request` | integer ("0" | "1") | No | When set to 1, the various request parameters are added to the response for debugging |
| `countrycode` | string | No | Restrict forward geocoding results to specific countries. ISO 3166-1 Alpha 2 codes, comma-separated for multiple |
| `address_only` | integer ("0" | "1") | No | When set to 1, include only the address (excluding POI names) in the formatted string |
| `no_annotations` | integer ("0" | "1") | No | When set to 1, results will not contain annotations |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Reverse Geocode Coordinates

**Slug:** `OPENCAGE_GEOCODE_REVERSE`

Tool to convert coordinates to a human-readable address. Use when you have latitude and longitude and need a readable location.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Latitude and longitude as a comma-separated string, e.g., '51.952659,7.632473' |
| `abbrv` | integer | No | 1 to abbreviate road and route types |
| `limit` | integer | No | Maximum number of results to return (1-10) |
| `pretty` | integer | No | 1 for pretty-printed JSON, 0 (default) for compact output |
| `language` | string | No | Preferred response language as ISO 639-1 code, e.g., 'en' |
| `roadinfo` | integer | No | 1 to include road information in the response |
| `add_request` | integer | No | 1 to include request parameters in the response |
| `countrycode` | string | No | Restrict results to one or more ISO 3166-1 alpha-2 country codes separated by commas |
| `normalizecity` | integer | No | 1 to normalize city names |
| `min_confidence` | integer | No | Minimum confidence level (0-10) to filter results |
| `no_annotations` | integer | No | 1 to exclude annotations in the response |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Geocode XML

**Slug:** `OPENCAGE_GEOCODE_XML`

Geocode a location query and return results in XML format. Supports both forward geocoding (address to coordinates) and reverse geocoding (coordinates to address). Use this when you need XML-formatted output instead of JSON.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Location query: use an address or place name for forward geocoding, or 'lat,lng' coordinates for reverse geocoding |
| `abbrv` | integer ("0" | "1") | No | Set to 1 to return abbreviated address components (e.g., 'CA' instead of 'California') |
| `limit` | integer | No | Maximum number of results to return (1-100). Default is 10 if not specified |
| `pretty` | integer ("0" | "1") | No | Set to 1 for human-readable formatted XML output, 0 or omit for compact output |
| `language` | string | No | IETF language tag for results (e.g., 'en' for English, 'de' for German, 'fr' for French) |
| `roadinfo` | integer ("0" | "1") | No | Set to 1 to include detailed road and driving information for the location |
| `no_dedupe` | integer ("0" | "1") | No | Set to 1 to return all results including duplicates, 0 or omit to deduplicate |
| `add_request` | integer ("0" | "1") | No | Set to 1 to include original request parameters in the response for debugging |
| `countrycode` | string | No | Restrict results to specific countries using comma-separated ISO 3166-1 alpha-2 codes (e.g., 'us,ca' for USA and Canada) |
| `min_confidence` | integer | No | Filter results to only include those with confidence score at or above this value (1-10, where 10 is highest) |
| `no_annotations` | integer ("0" | "1") | No | Set to 1 to exclude supplementary annotations (timezone, currency, etc.), 0 or omit to include |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Check API Health

**Slug:** `OPENCAGE_PING_OPENCAGE`

Tool to check API health and connectivity. Returns 'pong' if the API is reachable. Use when you need to verify that the OpenCage API is accessible and operational.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |