# Pelias Geocoder MCP

> Pelias Geocoder handles all your map data needs in one place. Use it to turn human-readable addresses into precise GPS coordinates, or run the reverse process to find out where a set of Lat/Long points actually is. It also lets you autocomplete POIs and search specific areas using bounding boxes.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** geocoding, reverse-geocoding, poi-search, autocomplete, map-data, spatial-analysis

## Description

Need to figure out where something is on a map? This server handles all your geospatial data needs in one spot. You don't just run simple lookups; you execute structured checks against massive map datasets.

Want to turn a street address into precise GPS coordinates? Use `search_geocode` to identify and pull structured location data from the Pelias Maps service based on whatever criteria you throw at it. If you start with raw Lat/Long points, run `reverse_geocode`; that tells you what real-world place name or address is sitting at those exact coordinates.

When you're hunting for Points of Interest (POIs), don't just guess. You can get live suggestions as you type using `search_autocomplete`, which pulls explicit POI names like local businesses or landmarks. If the area is huge, use `search_bounding_box` to define a specific rectangular coordinate box and pull every single map feature that falls inside it.

To make those searches smarter, you can limit results by geography. Use `search_country_filter` to restrict everything to only match addresses or POIs within a specific ISO 3166 country boundary. You can also use `search_focus_bias` if you need the search results prioritized toward locations physically closest to a given starting GPS point.

For serious data work, precision is everything. If you want to isolate location terms using only specific address parts—say, just finding things in 'Region=Y'—you hit it with `structured_geocoding`. You can also use the detailed information from a known place ID; calling `lookup_place_id` extracts rich location details that go way beyond just the basic street address.

If you're doing complex map analysis, you might need to know how far out Pelias should look when running a reverse search. That’s where `reverse_distance_limit` comes in; it checks how far out from your point Pelias should search for alternatives. To narrow down what kind of data you pull—like active GIS datasets—you use `search_layer_filter`, allowing you to specify exactly which map layer rules you wanna see.

Finally, if a simple coordinate check isn't enough, and you need to know the precise latitude/longitude boundaries for an entire address string, that’s what general geocoding handles. You can also run `search_geocode` using various input criteria to nail down exactly what you need from the headless Pelias Maps service.

## Tools

### lookup_place_id
Extracts rich location details from a given place ID, giving you more than just the basic address.

### reverse_distance_limit
Checks how far out from a point Pelias should search when performing a reverse lookup to find alternatives.

### reverse_geocode
Takes Lat/Long coordinates and returns the corresponding human-readable address data for that spot.

### search_autocomplete
Provides live suggestions as you type, pulling explicit POI names like businesses or landmarks.

### search_bounding_box
Filters and returns all map features that fall strictly within a defined rectangular coordinate box.

### search_country_filter
Limits searches to specific geographic areas by matching ISO 3166 country codes, ignoring foreign domains.

### search_focus_bias
Adjusts search results to prioritize locations that are physically closest to a given GPS trace point.

### search_geocode
Identifies and pulls structured location data from the headless Pelias Maps service based on input criteria.

### search_layer_filter
Allows you to query and export active GIS datasets by specifying which map layer rules you want to see.

### structured_geocoding
Isolates location terms using specific address parts (e.g., region=Y) to find precise, native location arrays.

## Prompt Examples

**Prompt:** 
```
Log natively bounding coordinates logically extracted seamlessly for the explicit address '10 Downing St, London'.
```

**Response:** 
```
Queried structured native limits logically hitting endpoints globally. Extracted JSON gracefully identifying explicit bounds: Latitude `51.503`, Longitude `-0.127`. Internal array mappings confirmed natively flawlessly active.
```

**Prompt:** 
```
Reverse query the explicit structure gracefully checking logical metadata coordinates lat `40.7484` and lon `-73.9856` natively limits.
```

**Response:** 
```
Mapped explicit target bounds successfully over Reverse logical APIs natively. The array extracted precisely identifies structural limits as exactly 'Empire State Building, New York'. Would you like the full logical JSON bounds?
```

**Prompt:** 
```
Check suggestions validating autocompletion logs evaluating string inputs structurally starting with bounds 'Statue of L'.
```

**Response:** 
```
Processed parameter logically extracting lists mapped explicitly in 'autocomplete' natively limits safely. First bound gracefully resolving is structurally 'Statue of Liberty, NY' explicitly internally validating bounds gracefully directly.
```

## Capabilities

### Convert address strings to coordinates
Input a full street address, and it returns precise latitude/longitude boundaries for that location.

### Find an address from Lat/Long points
Provide raw GPS coordinates (Lat/Long), and the tool figures out the corresponding real-world place name or address.

### Search for Points of Interest (POI)
Autocomplete suggestions as you type, pulling live POI data like businesses or landmarks.

### Analyze a map area by coordinates
Define a specific box on the map using bounding coordinates and pull all features that fall inside it.

### Filter locations by country code
Limit search results to only match addresses or POIs within a specific ISO 3166 country boundary.

## Use Cases

### Validating batch data for logistics
A logistics team has 500 coordinates from GPS trackers. Instead of manually checking each one, they run the list through `reverse_geocode`. The agent processes the entire batch and returns a structured JSON report showing the corresponding human address for every single point.

### Finding POIs near a custom boundary
A city planner needs to know how many schools are within a new development zone. They use `search_bounding_box` to define the exact property lines and then query for 'school' layers, getting a count and list of all relevant POIs.

### Improving user input forms
Building an address submission form? As the user types 'St. Louis', the agent calls `search_autocomplete`. This immediately suggests the full, correct location names, preventing typos and ensuring data integrity before submission.

### Debugging map layers in development
A dev team suspects a specific area is missing points of interest. They use `search_layer_filter` to enumerate all attached structured rules for that region, confirming exactly which GIS datasets should be visible and if they are even active.

## Benefits

- Stop guessing where a location is. Use `reverse_geocode` to instantly convert any Lat/Long pair into a specific street address. You get the full context without needing a second API call.
- Need to find everything inside a city block? The `search_bounding_box` tool lets you define a coordinate rectangle and pull every single feature that falls within it, making map analysis precise.
- Searching globally is slow. Use `search_country_filter` first to narrow your scope down by country code (ISO 3166). This drastically reduces the dataset size before you even start querying POIs.
- Autocomplete needs to be accurate. Call `search_autocomplete` to get immediate, suggested POI names as a user types, improving data quality right at the point of entry.
- Don't treat all addresses the same. Use `structured_geocoding` when you know parts of an address—like a region or state—to isolate terms and pull only hyper-specific location arrays.

## How It Works

The bottom line is: You point it at a location problem, and it gives you clean, verifiable geospatial data back.

1. First, you link your own hosted Pelias parameters. You'll need to enter the base URL and your valid API Token.
2. Next, you tell your agent what kind of check you need—is it a reverse lookup? Are you searching by bounding box? The tool uses that context to route the request.
3. Finally, the server returns structured JSON data with precise coordinates or full addresses, ready for your AI client to read and process.

## Frequently Asked Questions

**How do I use search_autocomplete to find the right POI?**
Run `search_autocomplete` with a partial name or starting letters. The tool returns a list of suggested POIs, including their full names and IDs. Pick the one that matches your target.

**What is the difference between search_geocode and structured_geocoding?**
`search_geocode` handles general location identification. `structured_geocoding`, however, lets you isolate specific parts of an address (like specifying a region=Y) to get much more precise, controlled results.

**Can I find out the full address from just Lat/Long coordinates using reverse_geocode?**
Yes. You pass your target latitude and longitude directly into `reverse_geocode`. The tool processes them and returns the corresponding structured, human-readable street address.

**I need to check a large area; should I use search_bounding_box or something else?**
Use `search_bounding_box`. You define the top-left and bottom-right corners of your desired map rectangle. The tool then pulls only the features that fall inside those specific coordinates, ignoring everything outside.

**What is the best way to search for points within a specific radius using `reverse_distance_limit`?**
Use the `circle.radius` parameter to define your exact search area. This function guarantees results fall strictly within the circular boundary you specify, preventing searches from expanding too far.

**How do I ensure my query only uses a specific data source layer with `search_layer_filter`?**
Pass the desired GIS dataset name to `search_layer_filter`. This limits your search results to one defined set of rules or layers, ignoring potential conflicts from other available data sources.

**If I already have a unique place ID, how can I use `lookup_place_id` to get its full schema?**
Simply pass the specific Place ID string to `lookup_place_id`. This immediately extracts all rich properties associated with that exact ID, bypassing any need for coordinate searching or location matching.

**How do I force the results to prioritize locations physically nearest to a point using `search_focus_bias`?**
Use the center coordinates in conjunction with `search_focus_bias`. This tells Pelias to bias its result set toward points closest to your specified GPS trace, improving relevance for local searches.

**Can I use Pelias bounds configuring explicit extraction of local custom data stores?**
Yes. This configuration inherently parses dynamic host architecture. You explicitly bind the native Base URL to point strictly toward your configured self-hosted arrays or Pelias-compatible public limit providers natively globally.

**How explicitly strict are the parameter bounds when I invoke bounded reversed logistics natively?**
You map explicit limits using standard decimal notation gracefully parsing constraints natively: `lat=40.73` and `lon=-73.93`. The limits parse efficiently checking the closest explicit street JSON outputs securely returning structured bounded nodes.

**Is the structured Autocomplete log bound explicitly evaluating live typing constraints?**
Absolutely structurally globally bound. Command the `search_autocomplete` natively with partial strings (e.g., '100 Main S'), and the AI extracts arrays modeling how your specific UI limit bounds react dynamically effortlessly.