# Geocode.xyz MCP

> Geocode.xyz converts physical addresses into precise latitude and longitude coordinates; it also reverses the process to find an address from GPS points. This MCP extracts location names from messy text, checks where IP addresses originated, and suggests completions for better data entry.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** geocoding, reverse-geocoding, geoparsing, location-data, ip-geolocation

## Description

Need to work with locations but hate manually verifying every street name or cross-referencing maps? This connector gives your AI agent global geographic intelligence on demand. It handles five different kinds of location queries: converting a written address into coordinates, taking GPS points and finding the nearest physical place, automatically pulling out location names from huge chunks of text, determining where an IP address is located, and suggesting completions for partial entries.

When you connect Geocode.xyz through Vinkius, your AI client can query this data directly. You stop worrying about formatting or which API endpoint to hit. Instead, you just ask: 'What are the coordinates for that?' The system does the heavy lifting, giving you clean, verifiable spatial data instantly.

## Tools

### autocomplete
Provides suggestions for partial street names, postal codes, or city names as you type them.

### forward_geocode
Converts a human-readable place name or address into precise geographic coordinates.

### geoparse
Scans long, messy blocks of text and extracts every location name it can identify.

### ip_geolocation
Looks up the geographical origin (city and country) associated with any provided IP address.

### reverse_geocode
Converts a set of latitude and longitude coordinates back into a readable physical street address.

## Prompt Examples

**Prompt:** 
```
Find the coordinates for 'The Colosseum in Rome'.
```

**Response:** 
```
I've located the Colosseum. The coordinates are Latitude: 41.8902, Longitude: 12.4922.
```

**Prompt:** 
```
What address is located at latitude 48.8584 and longitude 2.2945?
```

**Response:** 
```
The coordinates 48.8584, 2.2945 correspond to the Eiffel Tower, located at Champ de Mars, 5 Avenue Anatole France, 75007 Paris, France.
```

**Prompt:** 
```
Extract all locations from this text: 'Our team is traveling from New York to London next week.'
```

**Response:** 
```
I've parsed the text and found two locations: 'New York' (USA) and 'London' (United Kingdom).
```

## Capabilities

### Find Coordinates from Addresses
It takes any readable address—a city, a landmark, or a street name—and spits out precise latitude and longitude numbers.

### Address Points by GPS
Give it coordinates, and it tells you the most likely physical mailing address associated with that point.

### Extract Locations from Text
It scans unstructured documents or paragraphs and pulls out every location name it finds, regardless of how messy the text is.

### Locate an IP Address
You provide an IP address, and the tool returns its geographical origin, including the city and country.

### Suggest Typing Completions
When you type a partial street name or postal code, it offers accurate suggestions to keep your data clean.

## Use Cases

### Building a Delivery App
A logistics manager needs to verify if the customer's submitted ZIP code and street name are accurate. They ask their agent to run `forward_geocode` on the input, which returns the necessary coordinates for the routing API, ensuring the delivery truck knows exactly where to go.

### Analyzing Customer Reviews
A content manager receives a large batch of unstructured customer reviews. They use `geoparse` to automatically pull out every location mentioned—'New York,' 'The coast,' 'near Miami'—allowing them to track regional popularity without reading the text.

### Investigating Network Traffic
A security analyst intercepts a log file containing an unknown IP address. They run `ip_geolocation` on the IP, which immediately tells them it originated from Dublin, Ireland, narrowing down the investigation instantly.

### Building User Forms
A web developer is building a multi-step form. Instead of letting users freely type an address, they integrate `autocomplete` to guide input, ensuring that when the user finally submits the data, it's clean and ready for `forward_geocode`.

## Benefits

- Saves time on manual verification: Instead of manually checking every address in a spreadsheet against Google Maps, use `forward_geocode` to instantly get coordinates for thousands of entries.
- Handles messy content: If you're pulling location mentions from customer feedback or articles, `geoparse` automatically extracts all the locations without you needing regex rules.
- Improves data quality: When users are entering addresses into a form, use `autocomplete` to guide them and prevent simple spelling errors that break downstream processes.
- Supports remote tracking: Need to know where an unknown IP address came from? Run `ip_geolocation` to get the city and country immediately for security or fraud checks.
- Completes data sets: If you only have GPS coordinates (like from a tracker), use `reverse_geocode` to write out a clear, human-readable street address.

## How It Works

The bottom line is that you just ask for location intelligence, and your agent handles the complex API calls behind the scenes.

1. First, subscribe to this MCP and enter your Geocode.xyz API Key into the Vinkius platform.
2. Next, direct your AI client to perform a location query (e.g., 'What are the coordinates for...').
3. The system processes the request using the necessary geocoding method and returns precise coordinate data or verified addresses.

## Frequently Asked Questions

**How does geoparse work with long documents?**
It uses a specific POST method to handle large volumes of text, which means it won't fail on big articles or documents. It focuses solely on extracting location names from free-form writing.

**Can I use forward_geocode if the address is incomplete?**
While it works best with full addresses, you can provide partial information and let the tool attempt to find the most likely match. However, for guaranteed accuracy, providing the complete name is always better.

**What's the difference between ip_geolocation and forward_geocode?**
Forward geocoding takes a written street address (like '123 Main St'). IP geolocation takes an internet address (a string of numbers) and tells you where that connection point is.

**Does autocomplete help with postal codes only?**
No. It helps with several things, including partial street names, city names, and postal codes. You can use it to improve accuracy across multiple data fields simultaneously.

**What happens if I call `forward_geocode` with an address that doesn't exist?**
The MCP returns a specific error message indicating the location could not be found. This prevents your agent from treating bad data as valid coordinates, so you know exactly where the input failed.

**If I call `reverse_geocode` with impossible latitude/longitude values, what result do I get?**
It returns an error status stating that the coordinates are outside known geographical boundaries. This is crucial for maintaining data integrity and ensuring your agent doesn't proceed with invalid points.

**Does calling `geoparse` repeatedly in quick succession trigger rate limits, and how should I handle them?**
Yes, high-volume requests are subject to standard rate limiting. Your AI client must implement a retry mechanism with exponential backoff if it encounters a 429 status code.

**When using `autocomplete`, are the suggestions limited only to street names, or can they include postal codes and cities?**
The tool suggests multiple location components. You'll receive structured results covering partial street names, city identifiers, and corresponding postal code options all in one call.

**Can I extract multiple location names from a long paragraph of text?**
Yes! Use the `geoparse` tool. Provide the text in the `scantext` parameter, and the agent will identify and return all geographic locations mentioned within that text.

**How do I find the address for a specific set of GPS coordinates?**
Use the `reverse_geocode` tool. Simply provide the `lat` (latitude) and `long` (longitude) values, and the server will return the closest physical address.

**Is it possible to locate a user based on their IP address?**
Yes, the `ip_geolocation` tool allows you to input an IP address and retrieve the associated city, region, and country data.