# OpenCage Geocoder MCP > OpenCage Geocoder converts addresses to latitude/longitude coordinates and coordinates back to formatted street addresses worldwide. This server gives your AI client high-precision global geocoding and reverse geocoding using one reliable API. It handles city names, landmarks, ZIP codes, and specific international formats across the globe. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** geocoding, reverse-geocoding, maps, location-data, coordinates ## Description When you're dealing with location data, you gotta convert between addresses and coordinates constantly. The **OpenCage Geocoder** handles that whole round trip for your agent. This server gives your AI client the high-precision tools it needs to map anything globally. ### How It Works Your agent uses two primary functions: `forward_geocode` and `reverse_geocode`. You don't need to worry about the underlying API calls; you just tell your client what location data you have, and it handles the rest. **Using `forward_geocode` (Address to Coordinates)** When you pass in a physical address, place name, or landmark string, this tool spits out precise latitude and longitude numbers. It's reliable for everything: just a street corner, an entire city block, or even a specific ZIP code area. You can feed it anything from 'Times Square, New York' to 'The Eiffel Tower' and get coordinates back instantly. What’s really useful is that you don't have to pick one format—it handles different international address standards globally. If you need extra detail, the tool can also grab specific road info; for instance, it tells you which nearest major road matches the location you provided. **Using `reverse_geocode` (Coordinates to Address)** If your agent only has coordinates—say, lat 34.0522 and lon -118.2437—this tool flips it around. It takes those raw numbers and turns them into a full, structured, readable street address. This isn't just random text; the output is formatted exactly like an actual mailing address, complete with necessary location metadata you need for databases or reports. ### Global Scope and Flexibility The coverage here is huge. It doesn't pull data from one place; it aggregates multiple open sources—think OpenStreetMap and other reliable global datasets—meaning it covers nearly every geographic region on the planet. You can specify exactly what language you want the results in, or what format your application needs, ensuring the output integrates smoothly into whatever system you’re running. For instance, if you're processing international data, you might run `forward_geocode` with an address written in French, and the server gives you coordinates. Then, later on, when validating that point, you use `reverse_geocode` to ensure the resulting street address is also formatted correctly for a different language. It’s seamless because the underlying mechanism handles the linguistic complexity. Don't try building this yourself with multiple APIs; it'll be a nightmare of keys and formatting rules. This server consolidates all that complex geocoding logic into one reliable, straightforward toolset. You just call `forward_geocode` or `reverse_geocode`, and you get clean, structured data back every time. ## Tools ### forward_geocode Converts a physical address or place name string into precise geographic latitude and longitude coordinates. ### reverse_geocode Takes known latitude and longitude coordinates and returns the full, formatted street address details for that point on Earth. ## Prompt Examples **Prompt:** ``` What are the coordinates for the Eiffel Tower in Paris? ``` **Response:** ``` I've geocoded the Eiffel Tower. The coordinates are Latitude 48.85837, Longitude 2.29448. It is located at Champ de Mars, 5 Avenue Anatole France, 75007 Paris, France. ``` **Prompt:** ``` What is the address at latitude 52.51627 and longitude 13.37772? ``` **Response:** ``` The address for those coordinates is Brandenburger Tor, Pariser Platz, 10117 Berlin, Germany. ``` **Prompt:** ``` Find 'Main Street' but only in the United Kingdom and return the result in French. ``` **Response:** ``` Searching for 'Main Street' in the UK... I found a primary result: Main Street, Gibraltar, Royaume-Uni (Note: Gibraltar is a British Overseas Territory). Would you like to see other matches within the UK? ``` ## Capabilities ### Convert Address Text to Coordinates You pass a physical address or place name, and the server returns precise latitude and longitude values. ### Convert Coordinates back to Address The agent takes coordinates (lat/lon) and converts them into a structured, readable street address format. ### Handle Multiple Languages You request the results in specific languages or formats for your application's needs. ### Retrieve Road Details The server can optionally pull extra road info, like which nearest road matches a location. ## Use Cases ### Validating Shipping Addresses A user submits a shipping address via a web form. Instead of trusting it, your agent runs `forward_geocode`. If the coordinates return successfully and match the expected region, you know the address is valid for routing. ### Finding a Point on a Map You have GPS data (latitude/longitude) from a tracking device. You need to tell your user what street they are at. Your agent runs `reverse_geocode` and gets the formatted address: '123 Main Street, Anytown.' ### Data Enrichment for CRM Your data team has a spreadsheet of old records with just city names. To make them usable in a map viewer, your agent iterates through the list and runs `forward_geocode` on every single entry to pull coordinates. ### Global Search Query Handling A user asks for 'Main Street' but doesn't specify the country. Your agent uses `forward_geocode`, allowing you to pass filters (like Country: UK) to narrow down results and prevent ambiguity. ## Benefits - You get accurate coordinates for anything. Use `forward_geocode` to take a street name and instantly get the precise lat/lon pair needed for mapping services. - Reverse lookups are simple. Give your agent coordinates, and it uses `reverse_geocode` to give you the full address details—no manual parsing required. - It handles international stuff. You don't have to write separate logic for different country formats; the API manages global coverage. - Better data cleaning means less time debugging. Feed messy addresses into a geocoding workflow, and get structured coordinates back every time. - You control the output format. The server lets you specify languages or fields, so the result matches exactly what your app expects. ## How It Works The bottom line is that it lets your AI client talk to global mapping data without you having to manage a complex database yourself. 1. First, you subscribe to the OpenCage Geocoder and supply your personal API Key to the MCP. 2. Next, you ask your agent for a specific lookup—either an address-to-coordinate job or coordinates-to-address job. 3. The server runs the relevant function (like `forward_geocode`) and returns structured JSON containing the required latitude, longitude, and formatted text. ## Frequently Asked Questions **How does OpenCage Geocoder MCP Server handle addresses in different countries?** It handles global coverage by pulling data from multiple sources like OpenStreetMap. You don't need to write separate logic for UK versus US address formats; the server manages that complexity. **What is the difference between `forward_geocode` and `reverse_geocode`?** `forward_geocode` takes text (like an address) and gives you coordinates. `reverse_geocode` does the opposite: it takes coordinates and figures out the best matching street address. **Can I get road information using OpenCage Geocoder MCP Server?** Yes, besides basic lat/lon, you can optionally retrieve specific road data. This helps verify nearest roads or pull attribute details for routing services. **What if the address I give to `forward_geocode` is wrong?** The server will return null values or an error message, letting your agent know the lookup failed. It's built to handle ambiguous or invalid inputs gracefully. **How do I set up OpenCage Geocoder MCP Server with my API key?** You must provide your specific OpenCage API key when connecting to the server. The agent uses this key for authorization, ensuring all calls remain within your account's usage limits. **What happens if I hit rate limits when calling `forward_geocode`?** The server immediately returns an error status code indicating the limit breach. You must build backoff logic into your agent's workflow to wait and retry later. **If I use `forward_geocode` for a vague location, will it return one result or many?** The server returns an array of potential matches if the input is ambiguous. Your AI client needs logic to process this list and select the best geographic fit. **Can I control the language of the address returned by `reverse_geocode`?** Yes, you pass a locale parameter with the coordinates. This forces the API to return formatted address elements in your desired language for better user experience. **Can I limit the search results to a specific country?** Yes! Use the `countrycode` parameter in the `forward_geocode` tool with ISO 3166-1 alpha-2 codes (e.g., 'us' for USA, 'br' for Brazil) to restrict results to that territory. **How do I get the address of a specific set of coordinates?** Use the `reverse_geocode` tool by providing the `lat` (latitude) and `lng` (longitude). The agent will return the most accurate formatted address found for those coordinates. **Can I get information about the nearest road to a location?** Yes. By setting the `roadinfo` parameter to true in either `forward_geocode` or `reverse_geocode`, the API will attempt to match the location to the nearest road and include road-specific data in the response.