# Mapbox Geospatial Operations

Adopt this skill: https://proskills.md/skills/other/mapbox-geospatial-operations

Page: https://proskills.md/skills/other/mapbox-geospatial-operations
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8049

```text
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:

Offline Geometric Tools - Use Turf.js for pure geometric/spatial calculations

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 CharacteristicTool CategoryWhy
Straight-line distance (as the crow flies)Offline geometricAccurate for geometric distance
Road/path distance (as the crow drives)Routing APIOnly routing APIs know road networks
Travel timeRouting APIRequires routing with speed/traffic data
Point containment (is X inside Y?)Offline geometricPure geometric operation
Geographic shapes (buffers, centroids, areas)Offline geometricMathematical/geometric operations
Traffic-aware routingRouting APIRequires real-time traffic data
Route optimization (best order to visit)Routing APIComplex routing algorithm
High-frequency checks (e.g., real-time geofencing)Offline geometricInstant response, no latency

Decision Matrices by Use Case

Distance Calculations

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

What They Actually MeanTool ChoiceWhy
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 timedirections_tool
 or matrix_tool
Requires routing with speed data
Distance with current trafficdirections_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 TypeTool ChoiceWhy
"Within X meters radius"distance_tool
 + filterSimple 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?"

Create zone → isochrone_tool
 (routing API - need travel time)

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?"

ScenarioTool ChoiceWhy
A to B directionsdirections_tool
Turn-by-turn routing
Optimal order for multiple stopsoptimization_tool
Solves traveling salesman problem
Clean GPS tracemap_matching_tool
Snaps to road network
Just need bearing/compass directionbearing_tool
Simple geometric calculation
Route with trafficdirections_tool
 (driving-traffic)Real-time traffic awareness
Fixed-order waypointsdirections_tool
 with waypointsRouting 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"

RequirementTool ChoiceWhy
Simple circular bufferbuffer_tool
Geometric circle/radius
Travel-time zoneisochrone_tool
Based on routing network
Calculate area sizearea_tool
Geometric calculation
Simplify complex boundarysimplify_tool
Geometric simplification
Find center of shapecentroid_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 CaseApproachTool Choice
Real-time geofencing (every second)Geometric checkspoint_in_polygon_tool
 (instant)
Route planning (one-time)Full routingdirections_tool
 or optimization_tool

Periodic proximity checksGeometric distancedistance_tool

Live traffic routingRouting with trafficdirections_tool
 (driving-traffic)

Architecture note for high-frequency geofencing: If the application calls containment checks at very high rates (e.g., 50 vehicles every 2 seconds = 25 checks/second), calling MCP tools over the network adds agent-reasoning overhead that makes it impractical. In those cases, recommend using Turf.js directly in-process (turf.booleanPointInPolygon
) for the hot path, and reserve MCP tools for peripheral tasks like zone definition (isochrone_tool
), rerouting (directions_tool
), or visualization (static_map_image_tool
).

Common Scenarios and Optimal Approaches

Scenario 1: Store Locator

User: "Find the closest store and show 5km coverage"

Optimal approach:

Search stores → category_search_tool
 (returns distances automatically)

Create coverage zone → buffer_tool
 (5km geometric circle)

Visualize → static_map_image_tool

Why: Search already gives distances; geometric buffer for simple radius

Scenario 2: Delivery Route Optimization

User: "Optimize delivery to 8 addresses / stops"

Optimal approach:

Geocode addresses (if needed) → Use search_and_geocode_tool
 to convert any street addresses to coordinates. Even when coordinates are already provided, mention this as an optional pre-step — real-world delivery lists often contain a mix of addresses and coordinates.

Optimize route → optimization_tool
 (TSP solver — reorders stops to minimize total drive time)

Why optimization_tool
 and NOT these alternatives:

directions_tool
 only routes A → B (or through fixed-order waypoints). It does NOT reorder stops — if you pass 8 stops, it routes them in the order given, which is almost never optimal.

matrix_tool
 gives travel times between all pairs of stops (8×8 = 64 values), but it does NOT compute the optimal ordering. You'd need to solve TSP yourself on top of the matrix — optimization_tool
 does this for you in one call.

Always mention search_and_geocode_tool
 as a useful companion for geocoding delivery addresses before optimization.

Scenario 3: Service Area Validation

User: "Which of these 200 addresses can we deliver to in 30 minutes?"

Optimal approach:

Create delivery zone → isochrone_tool
 (30-minute driving)

Check each address → point_in_polygon_tool
 (200 geometric checks)

Why: Routing for accurate travel-time zone, geometric for fast containment checks

Scenario 4: GPS Trace Analysis

User: "How long was this bike ride?"

Optimal approach:

Clean GPS trace → map_matching_tool
 (snap to bike paths)

Get distance → Use API response or calculate with distance_tool

Why: 
```
