mapbox-geospatial-operations

What this skill does

# Mapbox Geospatial Operations Skill

Expert guidance for AI assistants on choosing the right geospatial tools from the Mapbox MCP Server. Focuses on selecting tools based on **what the problem requires** - geometric calculations vs routing, straight-line vs road network, and accuracy needs.

## Core Principle: Problem Type Determines Tool Choice

The Mapbox MCP Server provides two categories of geospatial tools:

1. **Offline Geometric Tools** - Use Turf.js for pure geometric/spatial calculations
2. **Routing & Navigation APIs** - Use Mapbox APIs when you need real-world routing, traffic, or travel times

**The key question: What does the problem actually require?**

### Decision Framework

| Problem Characteristic                                 | Tool Category     | Why                                      |
| ------------------------------------------------------ | ----------------- | ---------------------------------------- |
| **Straight-line distance** (as the crow flies)         | Offline geometric | Accurate for geometric distance          |
| **Road/path distance** (as the crow drives)            | Routing API       | Only routing APIs know road networks     |
| **Travel time**                                        | Routing API       | Requires routing with speed/traffic data |
| **Point containment** (is X inside Y?)                 | Offline geometric | Pure geometric operation                 |
| **Geographic shapes** (buffers, centroids, areas)      | Offline geometric | Mathematical/geometric operations        |
| **Traffic-aware routing**                              | Routing API       | Requires real-time traffic data          |
| **Route optimization** (best order to visit)           | Routing API       | Complex routing algorithm                |
| **High-frequency checks** (e.g., real-time geofencing) | Offline geometric | Instant response, no latency             |

## Decision Matrices by Use Case

### Distance Calculations

**User asks: "How far is X from Y?"**

| What They Actually Mean                            | Tool Choice                         | Why                                      |
| -------------------------------------------------- | ----------------------------------- | ---------------------------------------- |
| Straight-line distance (as the crow flies)         | `distance_tool`                     | Accurate for geometric distance, instant |
| Driving distance (as the crow drives)              | `directions_tool`                   | Only routing knows actual road distance  |
| Walking/cycling distance (as the crow walks/bikes) | `directions_tool`                   | Need specific path network               |
| Travel time                                        | `directions_tool` or `matrix_tool`  | Requires routing with speed data         |
| Distance with current traffic                      | `directions_tool` (driving-traffic) | Need real-time traffic consideration     |

**Example: "What's the distance between these 5 warehouses?"**

- As the crow flies → `distance_tool` (10 calculations, instant)
- As the crow drives → `matrix_tool` (5×5 matrix, one API call, returns actual route distances)

**Key insight:** Use the tool that matches what "distance" means in context. Always clarify: crow flies or crow drives?

### Proximity and Containment

**User asks: "Which points are near/inside this area?"**

| Query Type                   | Tool Choice                                           | Why                                                           |
| ---------------------------- | ----------------------------------------------------- | ------------------------------------------------------------- |
| "Within X meters radius"     | `distance_tool` + filter                              | Simple geometric radius                                       |
| "Within X minutes drive"     | `isochrone_tool` → `point_in_polygon_tool`            | Need routing for travel-time zone, then geometric containment |
| "Inside this polygon"        | `point_in_polygon_tool`                               | Pure geometric containment test                               |
| "Reachable by car in 30 min" | `isochrone_tool`                                      | Requires routing + traffic                                    |
| "Nearest to this point"      | `distance_tool` (geometric) or `matrix_tool` (routed) | Depends on definition of "nearest"                            |

**Example: "Are these 200 addresses in our 30-minute delivery zone?"**

1. Create zone → `isochrone_tool` (routing API - need travel time)
2. Check addresses → `point_in_polygon_tool` (geometric - 200 instant checks)

**Key insight:** Routing for creating travel-time zones, geometric for containment checks

### Routing and Navigation

**User asks: "What's the best route?"**

| Scenario                            | Tool Choice                         | Why                               |
| ----------------------------------- | ----------------------------------- | --------------------------------- |
| A to B directions                   | `directions_tool`                   | Turn-by-turn routing              |
| Optimal order for multiple stops    | `optimization_tool`                 | Solves traveling salesman problem |
| Clean GPS trace                     | `map_matching_tool`                 | Snaps to road network             |
| Just need bearing/compass direction | `bearing_tool`                      | Simple geometric calculation      |
| Route with traffic                  | `directions_tool` (driving-traffic) | Real-time traffic awareness       |
| Fixed-order waypoints               | `directions_tool` with waypoints    | Routing through specific points   |

**Example: "Navigate from hotel to airport"**

- Need turn-by-turn → `directions_tool`
- Just need to know "it's northeast" → `bearing_tool`

**Key insight:** Routing tools for actual navigation, geometric tools for directional info

### Area and Shape Operations

**User asks: "Create a zone around this location"**

| Requirement               | Tool Choice      | Why                      |
| ------------------------- | ---------------- | ------------------------ |
| Simple circular buffer    | `buffer_tool`    | Geometric circle/radius  |
| Travel-time zone          | `isochrone_tool` | Based on routing network |
| Calculate area size       | `area_tool`      | Geometric calculation    |
| Simplify complex boundary | `simplify_tool`  | Geometric simplification |
| Find center of shape      | `centroid_tool`  | Geometric centroid       |

**Example: "Show 5km coverage around each store"**

- 5km radius → `buffer_tool` (geometric circles)
- "What customers can reach in 15 min?" → `isochrone_tool` (routing-based)

**Key insight:** Geometric tools for distance-based zones, routing tools for time-based zones

## Performance and Scale Considerations

### When Volume Affects Tool Choice

**Small operations (< 100 calculations):**

- Geometric tools: Instant, iterate freely
- Routing APIs: Fast enough for most uses

**Medium operations (100-1,000 calculations):**

- Geometric tools: Still fast, no concerns
- Routing APIs: Consider batch operations (matrix_tool)

**Large operations (> 1,000 calculations):**

- Geometric tools: May need optimization but still fast
- Routing APIs: Definitely use batch tools (matrix_tool handles up to 25×25)

**Key insight:** Volume rarely affects geometric tool choice, but routing APIs have batch tools for efficiency

### Real-Time vs Batch

| Use Case                            | Approach             | Tool Choice                              |
| ----------------------------------- | -------------------- | ---------------------------------------- |
| Real-time geofencing (every second) | Geometric checks     | `point_in_polygon_tool` (instant)        |
| Route planning (one-time)           | Full routing         | `directions_tool` or `optimization_tool` |
| Per