# OpenCage MCP

> OpenCage handles geocoding and reverse geocoding for your AI agent. You can convert any address to precise latitude/longitude coordinates, or turn GPS pins back into structured street addresses. The service offers filters like country restrictions, confidence scoring (1-10), and privacy modes for sensitive data.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** geocoding, reverse-geocoding, location-intelligence, spatial-analysis, timezone-data, data-validation

## Description

When your agent needs to figure out a location, OpenCage handles both ends of the street: converting a raw address string into precise coordinates, or taking a GPS pin and turning it back into a readable street address. You'll use these tools by calling them directly from your AI client.

**Forward Geocoding (Address to Coordinates)**

When you start with an address—say, '123 Main St'—you run the core lookup using `geocode_basic` for a general search within OpenCage boundaries. If that initial result is ambiguous or if you need confirmation on multiple delivery points, use `geocode_all_duplicate_results`; it retrieves structural matches confirming those alternative options. You don't wanna guess; you gotta be precise.

To make sure your location data is trustworthy enough for production, you can run the search with strict validation using `geocode_high_confidence`. This tool requires you to set explicit score limits (1–10), guaranteeing that the coordinates returned are highly validated. If you're working internationally, you don't want generic results; use `geocode_language_bias` to get results localized in a specific language code, like pt-BR, which handles tricky international address formats.

You can also narrow down your search dramatically using filters. To keep the location confined, employ `geocode_bounding_box`, which restricts searches to a precise geographic rectangle (a polygon). If you only care about one country, use `geocode_country_filter` and pass the specific two-letter code; this guarantees the address match belongs only to that nation. When privacy is your biggest concern, forget logging anything down. You run location lookups without OpenCage ever recording the query by calling `geocode_no_record_privacy`. 

**Reverse Geocoding (Coordinates to Address)**

If you've got a raw latitude/longitude pair—a GPS pin—and need to know what street it belongs to, start with `reverse_basic`. This lists structured rules that export active GPS data into an easily readable address format. For quick lookups where you just need the location array and don't want extra details slowing things down, use `reverse_fast_no_annotations`; this identifies accurate location arrays spanning native boundaries fast.

If you need more than just the street name from a pin, you can pull in time data. The `reverse_fetch_time_annotations` tool extracts UTC logic from GPS pins. That gives you historical validation limits like sunrise and sunset times for that exact spot.

Overall, your agent handles these tasks by converting addresses to coordinates or vice versa, while letting you restrict the results using filters for country code, bounding boxes, confidence scores, or language bias.

## Tools

### geocode_basic
Performs a general geocoding lookup within the OpenCage Engine boundaries.

### geocode_bounding_box
Restricts searches to a specific geographic rectangle (polygon) to pinpoint locations in a defined area.

### geocode_high_confidence
Runs an automated check that requires explicit score limits, returning highly validated location data.

### geocode_country_filter
Filters results by country code, ensuring the address match belongs only to that nation.

### geocode_language_bias
Retrieves results localized in a specific language code (e.g., pt-BR) for international address formats.

### geocode_all_duplicate_results
Retrieves structural matches confirming multiple delivery alternatives for an address.

### geocode_no_record_privacy
Generates secure mappings for geocoding queries without storing them in OpenCage's logs.

### reverse_basic
Lists structured rules to export active GPS pin data into a readable address format.

### reverse_fetch_time_annotations
Extracts UTC logic from GPS pins, providing historical validation limits like sunrise/sunset data.

### reverse_fast_no_annotations
Quickly identifies accurate location arrays spanning native boundaries for fast lookups when extra details aren't needed.

## Prompt Examples

**Prompt:** 
```
What are the coordinates for 1600 Amphitheatre Parkway, Mountain View, CA?
```

**Response:** 
```
Found 1 result with confidence 10/10. Latitude: 37.4220, Longitude: -122.0841. Timezone: America/Los_Angeles (UTC-7). County: Santa Clara. The result is formatted as '1600 Amphitheatre Parkway, Mountain View, CA 94043, United States'. Want me to run this through a different language?
```

**Prompt:** 
```
What's at coordinates 48.8566, 2.3522?
```

**Response:** 
```
Reverse geocoding result: Paris, Île-de-France, France. Formatted address: 'Rue de Rivoli, 75001 Paris, France'. Timezone: Europe/Paris (CET, UTC+1). Sunrise today: 07:12, Sunset: 19:45. Country code: FR. Want me to strip annotations for a faster, lighter response?
```

**Prompt:** 
```
Geocode 'Springfield' but only show results in the United States with confidence >= 7.
```

**Response:** 
```
Found 5 results in the US with confidence ≥ 7. Top match: Springfield, IL (confidence 9) — 39.7817, -89.6501 (state capital). Also: Springfield, MO (confidence 8), Springfield, MA (confidence 8), Springfield, OH (confidence 7), Springfield, OR (confidence 7). Want details on any of these?
```

## Capabilities

### Forward Geocoding
The agent takes an address string (e.g., '123 Main St') and returns the corresponding latitude/longitude coordinates.

### Reverse Geocoding
Given a lat/lng coordinate pair, the agent converts it into a readable street address format.

### Targeted Search Filtering
The system narrows down results using constraints like specific countries or bounding boxes to eliminate ambiguous matches.

### Confidence Scoring & Validation
You filter output by a minimum confidence level (1-10) to ensure the returned coordinates are accurate enough for production use.

### Privacy Mode Geocoding
The agent runs location lookups without OpenCage logging the query, protecting sensitive addresses in compliance with privacy requirements.

## Use Cases

### Validating Delivery Routes
A logistics team needs to confirm if '123 Main St, Miami' is a valid delivery point. They ask their agent to run `geocode_high_confidence` and filter by country (US). The tool returns coordinates with 9/10 confidence, confirming the address for dispatch.

### Building Global Address Books
A data engineer is building an international dataset. They ask their agent to geocode 'Av. Paulista' but need results localized in Portuguese (pt-BR). The agent uses `geocode_language_bias` to ensure the address format and metadata are correct for Brazil.

### Analyzing GPS Data Points
A developer gets a raw list of GPS coordinates from user tracking. They ask their agent to run `reverse_fetch_time_annotations`. The result doesn't just give the address; it also provides the UTC logic for local sunrise and sunset times, adding value.

### Bounding Search Area
A business needs coordinates for a specific commercial park defined by four corners. Instead of guessing an address, they ask their agent to use `geocode_bounding_box`. This tool constrains the search to that precise rectangular area.

## Benefits

- Avoid ambiguous location matches. Using `geocode_country_filter` forces results into a specific country, so you don't end up with misplaced addresses from another region.
- Improve data quality by enforcing minimum standards. The `geocode_high_confidence` tool runs an automated check that limits results to only the most reliable coordinates (score 1-10).
- Handle sensitive user input safely. When running lookups for private addresses, use `geocode_no_record_privacy`. OpenCage won't log the query, keeping your data secure.
- Speed up simple lookups. If you just need a coordinate fast and don't care about extra details, use `reverse_fast_no_annotations` to get results quickly.
- Structure complex searches. Need to find an address within a specific neighborhood? Use `geocode_bounding_box` to constrain the search area precisely.

## How It Works

The bottom line is: it turns raw text or raw GPS points into reliable, usable geospatial data that your application can act on.

1. First, you subscribe to this server and provide your unique OpenCage API Key.
2. Next, you tell your AI client (Claude, Cursor, etc.) what location task you need done—like 'Find coordinates for 1600 Amphitheatre Parkway'.
3. The agent calls the appropriate geocoding tool. You get back structured JSON containing coordinates, confidence scores, and formatted addresses.

## Frequently Asked Questions

**How do I prevent OpenCage from logging my private addresses using geocode_no_record_privacy?**
You simply call the `geocode_no_record_privacy` tool. This ensures that while your agent performs the lookup, the query is processed without being stored in OpenCage's logs, protecting sensitive user data.

**Should I use geocode_basic or geocode_high_confidence?**
For production code where accuracy matters, always prefer `geocode_high_confidence`. It runs an automated validation check that requires specific score limits, guaranteeing a much higher level of confidence than the basic lookup.

**Can I filter results to only show US addresses using geocode_country_filter?**
Yes. You use `geocode_country_filter` and pass the ISO 3166-1 Alpha-2 code 'US' (or any other country). This restricts all possible matches to that specific nation.

**How is reverse geocoding different from just calling a basic lookup?**
A standard lookup takes text and gives coordinates. Reverse geocoding, using `reverse_basic`, does the opposite: it takes raw GPS coordinates (lat/lng) and converts them back into a formatted street address.

**What is the benefit of using reverse_fetch_time_annotations?**
This tool goes beyond just listing an address. It extracts 'UTC logic' from the location pin, giving you crucial metadata like today's sunrise and sunset times for that specific coordinate.

**If I need the fastest possible coordinates lookup, should I use `reverse_basic` or `reverse_fast_no_annotations`?**
Use `reverse_fast_no_annotations`. It skips generating extra data like sunrise/sunset times and just provides the core location arrays. This cut significantly reduces payload size and improves response speed.

**When I use `geocode_bounding_box`, what defines the search area? Is it a simple rectangle?**
No, you define a specific polygon for the search area. This lets you constrain results to non-rectangular regions, which is essential when your target zone has irregular borders or specialized boundaries.

**If I run an address through `geocode_basic` and get multiple potential matches, how do I decide on the right one?**
The service provides a confidence score for each result. You can filter these results by setting a minimum required confidence level (e.g., >= 8) so your agent only acts on highly certain data.

**How accurate is the geocoding — can I use it for delivery routing?**
OpenCage returns a confidence score from 1 to 10 for each result. Use the high-confidence filter (min_confidence=8 or higher) to get delivery-grade accuracy. Combined with country filtering, you can eliminate ambiguous matches and get coordinates reliable enough for last-mile dispatch.

**What does privacy mode actually do?**
When you enable no_record=1, OpenCage processes your query but doesn't log it in their cache or analytics. The result is identical, but the query leaves no trace on their servers. Ideal for geocoding patient addresses, legal documents, or any PII-sensitive data.

**Can I geocode in multiple languages — like getting results in Portuguese for a Brazilian address?**
Yes. Use the language bias tool with any IETF language code (pt-BR, es-MX, fr-FR, etc.) and OpenCage returns the address components translated to that locale. Perfect for building multilingual apps or standardizing address formats across regions.