# Stadia Maps MCP

> Stadia Maps gives your AI client accurate, multi-layered geospatial intelligence. It handles everything from converting a physical address into exact coordinates (`forward_geocode`) to calculating complex travel time and distance matrices between dozens of points. You can run optimized routes for cars, bikes, or pedestrians, determine reachable areas using isochrones, and snap noisy GPS data straight onto official street networks.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** geospatial-routing, mapping, route-optimization, distance-matrix, logistics, coordinates

## Description

**Stadia Maps** gives your agent solid geospatial intelligence for everything from quick street lookups to complex logistics planning. You'll get precise data, no matter how messy the input is.

To nail down a location, you don't just guess; you confirm it first. If you start with a simple street address string, **`forward_geocode`** converts that into definite latitude and longitude coordinates. Before you even hit send on an address query, **`autocomplete_location`** suggests possible addresses, helping you narrow down the input options so your final results are accurate. Conversely, if you only have raw latitude/longitude points, **`reverse_geocode`** turns 'em back into a readable, structured physical address string.

When it comes to figuring out how people get around, these tools handle everything from simple travel estimates to optimizing entire multi-stop routes. You can run **`calculate_route`** between several coordinates and specify if the journey is by car, bike, or foot. For calculating distances and estimated times across a large set of distinct points—say, ten different distribution centers—you use **`calculate_distance_matrix`**, which computes all travel times and distances in one go. But if you're planning an entire trip with multiple stops, don't just connect 'em; you need the best sequence. That’s where **`optimized_trip_route`** steps in, figuring out the absolute best order of stops to minimize your total travel time or distance.

For strategic planning, you can use **`calculate_isochrone`** to map out a precise geographic area boundary; it shows exactly what's reachable from a central point based on a specific maximum driving time or distance. You also need to clean up messy data: if your GPS tracker sends noisy raw track points, run those through **`execute_map_matching`**, and it snaps the coordinates right onto the nearest official road network segment, making them trustworthy for logistics. For deep analysis, you can pull detailed elevation metrics for any given path or route using **`get_path_elevation`**. You can also determine the local time zone associated with specific latitude/longitude points by running **`get_timezone`**.

Here's the rundown of what happens:

*   **Geocoding:** The client converts a readable street address string into precise lat/long pairs using **`forward_geocode`**. It can also take raw coordinates and return the closest corresponding physical street address via **`reverse_geocode`**. To help users input data, **`autocomplete_location`** narrows down potential addresses as you type.
*   **Routing & Optimization:** You calculate paths between multiple points using **`calculate_route`**, specifying travel modes like car or bike. For complex logistics involving many stops, **`optimized_trip_route`** figures out the most efficient sequence to connect those locations and minimize overall distance or time. To get a full picture of distances across many potential start/end spots, **`calculate_distance_matrix`** computes all travel times and distances at once.
*   **Area Modeling & Data Integrity:** The agent determines an exact reachable area boundary (an isochrone) using **`calculate_isochrone`**, based on a time or distance limit. For dirty GPS data, **`execute_map_matching`** corrects raw tracks by snapping points to the official road network. Detailed elevation metrics for any path are retrieved with **`get_path_elevation`**. Finally, **`get_timezone`** determines the local time zone from specific coordinates.

## Tools

### autocomplete_location
Suggests potential addresses as you type, narrowing down input options before the final query.

### calculate_isochrone
Determines a precise geographic area boundary around a point based on maximum driving time or distance.

### calculate_distance_matrix
Computes and returns travel times and distances between a set of multiple starting and ending points.

### calculate_route
Calculates the path between several coordinates, allowing you to specify if travel is by car, bike, or foot.

### forward_geocode
Converts a simple street address string into definite latitude and longitude coordinates.

### get_path_elevation
Retrieves detailed elevation data for any given geographic path or route.

### get_timezone
Determines the local time zone associated with specific latitude and longitude points.

### execute_map_matching
Corrects raw GPS tracks by snapping the points onto the closest official road network segment.

### optimized_trip_route
Figures out the single best sequence of stops to connect multiple locations for maximum efficiency.

### reverse_geocode
Turns raw latitude/longitude coordinates back into a readable, structured physical address string.

## Prompt Examples

**Prompt:** 
```
Locate and securely return the comprehensive latitude and longitude values associated with this address: '1600 Amphitheatre Parkway, Mountain View, CA'.
```

**Response:** 
```
Initiating query analysis to index string formats effectively via `forward_geocode` targeting official datasets...

**Coordinates Resolved** 📍
- **Latitude:** `37.4225`
- **Longitude:** `-122.084`

The targeted input accurately evaluates to corresponding geographical metrics.
```

**Prompt:** 
```
Analyze these targeted locations formatting parameters into a complete trip route simulation enforcing an algorithmic analysis assuming optimal routing for automobiles.
```

**Response:** 
```
Evaluating parameters defined specifically for operation execution utilizing mode "auto" via `optimized_trip_route`.

**System Routing Computed and Sequenced**:
1. 🏁 Node Departure A (Lat: 40.71, Lon: -74.00)
2. 🚙 Logistical Intermediate Segment Node B (Lat: 40.75, Lon: -73.98)
3. 🏁 Objective Target Completion Target C (Lat: 40.78, Lon: -73.96)
```

## Capabilities

### Find coordinates from an address
The client converts a readable street address string into precise latitude and longitude pairs.

### Determine a location's physical address
The agent takes raw latitude and longitude points and returns the closest corresponding street address.

### Calculate travel time between multiple stops
The client computes distances and estimated travel times across several distinct geographic coordinates.

### Plot an efficient multi-stop route
The agent figures out the absolute best sequence of stops to minimize total travel time or distance for a whole trip.

### Model reachable areas (isochrones)
The client calculates and plots an area boundary based on a specific maximum driving time or distance from a central point.

### Clean raw GPS data to streets
It snaps unverified, noisy GPS track points onto the nearest official road network lines.

## Use Cases

### Optimizing Multi-Stop Delivery Routes
A fleet dispatcher needs the fastest route for 15 stops scattered across three counties. They don't want to manually check every permutation. Instead, they ask their agent: 'Plot the optimal sequence of these 15 coordinates.' The agent runs `optimized_trip_route` and returns the single best order of calls.

### Validating Field Survey Data
A GIS analyst collects GPS data from a test drive. The points are slightly off-road because the sensor was noisy. They run `execute_map_matching` on the raw track, and the tool snaps every single point onto the nearest valid road segment for accurate analysis.

### Calculating Service Boundaries
A store manager needs to know which neighborhoods are within a 10-mile driving radius of their new location. They use `calculate_isochrone` with a 10-mile radius, generating an exact polygon boundary for marketing and service planning.

### Preparing Logistics Models
A logistics engineer has addresses in three different states but needs to model the total travel cost. They use `forward_geocode` on all 30 addresses first, then feed those resulting coordinates into `calculate_distance_matrix` for a single data output.

## Benefits

- You stop guessing routes. Instead, you get mathematically proven paths by letting the agent run `optimized_trip_route` on a set of delivery points, guaranteeing the most efficient sequence.
- Stop dealing with messy GPS data. Use `execute_map_matching` to instantly align any raw vehicle track or field sensor reading to the official street grid, cleaning your dataset in seconds.
- You handle time zones correctly. By running `get_timezone`, you avoid errors when scheduling deliveries across multiple state lines or international borders that shift local clock times.
- You calculate service areas accurately. Instead of drawing circles on a map, use `calculate_isochrone` to precisely define the area reachable within 45 minutes of driving from your depot.
- You get complete context. Need to know where those coordinates are? Use `reverse_geocode`. It takes raw numbers and spits out a full street address string.

## How It Works

The bottom line is that your AI client can execute complex, multi-step location math just by calling the right tool function.

1. Connect the Stadia Maps MCP module to your AI client and provide the developer API key in the configuration.
2. Tell your agent exactly what you need: 'Calculate the most efficient route from Point A to B, stopping at C.'
3. The agent calls `optimized_trip_route`, returns a sequenced list of coordinates, and provides the total distance/time.

## Frequently Asked Questions

**Does it return visual maps or raw data?**
Raw structured JSON only — coordinates, distances, durations, and elevation values. No interactive map tiles are rendered. You can use the data to plot maps in your own application.

**Does `optimized_trip_route` solve the Traveling Salesman Problem?**
Yes. Pass an unordered set of coordinates and it returns the optimal visit sequence minimizing total travel time or distance.

**Is there a free tier?**
Yes. Stadia Maps offers a free tier with generous limits for geocoding, routing, and elevation queries. Sign up at stadiamaps.com and generate an API key from the dashboard.

**What format must the coordinates be when calling `calculate_route`?**
You must pass a JSON array of objects, where each object contains latitude and longitude. The tool expects the structure: `[{lat: number, lon: number}, ...]` for all waypoints.

**What happens if I run `forward_geocode` on an address that doesn't exist?**
The call returns a specific API error code and message detailing the failed lookup. Your AI client can then use standard try/catch logic to prompt the user for correction.

**Does `calculate_distance_matrix` have limits on how many locations I can input?**
While there is no hard limit in our documentation, we recommend keeping the number of points under 50 per batch request. Sending too many points will slow down processing.

**Is the path data fed into `get_path_elevation` required to be pre-matched using a tool like `execute_map_matching`?**
Yes, for accurate elevation readings, the input path should ideally be snapped to the street network. Use `execute_map_matching` first to clean raw GPS points.

**How do I handle API key security when setting up the Stadia Maps MCP Server?**
Always store your Developer API Key as an environment variable, never hardcoding it into client scripts. This keeps sensitive credentials outside of the codebase.