Mapbox Geospatial Operations

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: