Mapbox Geospatial Operations Skill

Core Principle: Problem Type Determines Tool Choice

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

Decision Framework

Decision Matrices by Use Case

Distance Calculations

distance_tool

directions_tool

directions_tool

directions_tool

matrix_tool

directions_tool

• 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)

Proximity and Containment

distance_tool

isochrone_tool

point_in_polygon_tool

point_in_polygon_tool

isochrone_tool

distance_tool

matrix_tool

1. Create zone →

   isochrone_tool

   (routing API - need travel time)
2. Check addresses →

   point_in_polygon_tool

   (geometric - 200 instant checks)

Routing and Navigation

directions_tool

optimization_tool

map_matching_tool

bearing_tool

directions_tool

directions_tool

• Need turn-by-turn →

  directions_tool

• Just need to know "it's northeast" →

  bearing_tool

Area and Shape Operations

buffer_tool

isochrone_tool

area_tool

simplify_tool

centroid_tool

• 5km radius →

  buffer_tool

  (geometric circles)
• "What customers can reach in 15 min?" →

  isochrone_tool

  (routing-based)

Performance and Scale Considerations

When Volume Affects Tool Choice

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

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

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

Real-Time vs Batch

point_in_polygon_tool

directions_tool

optimization_tool

distance_tool

directions_tool

Common Scenarios and Optimal Approaches

Scenario 1: Store Locator

1. Search stores →

   category_search_tool

   (returns distances automatically)
2. Create coverage zone →

   buffer_tool

   (5km geometric circle)
3. Visualize →

   static_map_image_tool

Scenario 2: Delivery Route Optimization

1. Geocode addresses →

   search_and_geocode_tool

2. Optimize route →

   optimization_tool

   (TSP solver with routing)

Scenario 3: Service Area Validation

1. Create delivery zone →

   isochrone_tool

   (30-minute driving)
2. Check each address →

   point_in_polygon_tool

   (200 geometric checks)

Scenario 4: GPS Trace Analysis

1. Clean GPS trace →

   map_matching_tool

   (snap to bike paths)
2. Get distance → Use API response or calculate with

   distance_tool

Scenario 5: Coverage Analysis

1. Create buffers around each location →

   buffer_tool

2. Calculate total area →

   area_tool

3. Or, if time-based →

   isochrone_tool

   for each location

Anti-Patterns: Using the Wrong Tool Type

❌ Don't: Use geometric tools for routing questions

// WRONG: User asks "how long to drive there?"
distance_tool({ from: A, to: B });
// Returns 10km as the crow flies, but actual drive is 15km

// CORRECT: Need routing for driving distance
directions_tool({
  coordinates: [
    { longitude: A[0], latitude: A[1] },
    { longitude: B[0], latitude: B[1] }
  ],
  routing_profile: 'mapbox/driving'
});
// Returns actual road distance and drive time as the crow drives

❌ Don't: Use routing APIs for geometric operations

// WRONG: Check if point is in polygon
// (Can't do this with routing APIs)

// CORRECT: Pure geometric operation
point_in_polygon_tool({ point: location, polygon: boundary });

❌ Don't: Confuse "near" with "reachable"

// User asks: "What's reachable in 20 minutes?"

// WRONG: 20-minute distance at average speed
distance_tool + calculate 20min * avg_speed

// CORRECT: Actual routing with road network
isochrone_tool({
  coordinates: {longitude: startLng, latitude: startLat},
  contours_minutes: [20],
  profile: "mapbox/driving"
})

❌ Don't: Use routing when bearing is sufficient

// User asks: "Which direction is the airport?"

// OVERCOMPLICATED: Full routing
directions_tool({
  coordinates: [
    { longitude: hotel[0], latitude: hotel[1] },
    { longitude: airport[0], latitude: airport[1] }
  ]
});

// BETTER: Just need bearing
bearing_tool({ from: hotel, to: airport });
// Returns: "Northeast (45°)"

Hybrid Approaches: Combining Tool Types

Pattern 1: Routing + Geometric Filter

1. directions_tool → Get route geometry
2. buffer_tool → Create corridor around route
3. category_search_tool → Find POIs in corridor
4. point_in_polygon_tool → Filter to those actually along route

Pattern 2: Routing + Distance Calculation

1. category_search_tool → Find 10 nearby locations
2. distance_tool → Calculate straight-line distances (geometric)
3. For top 3, use directions_tool → Get actual driving time

Pattern 3: Isochrone + Containment

1. isochrone_tool → Create travel-time zone (routing)
2. point_in_polygon_tool → Check hundreds of addresses (geometric)

Decision Algorithm

1. Does it require routing, roads, or travel times?
   YES → Use routing API (directions, matrix, isochrone, optimization)
   NO → Continue

2. Does it require traffic awareness?
   YES → Use directions_tool or isochrone_tool with traffic profile
   NO → Continue

3. Is it a geometric/spatial operation?
   - Distance between points (straight-line) → distance_tool
   - Point containment → point_in_polygon_tool
   - Area calculation → area_tool
   - Buffer/zone → buffer_tool
   - Direction/bearing → bearing_tool
   - Geometric center → centroid_tool
   - Bounding box → bounding_box_tool
   - Simplification → simplify_tool

4. Is it a search/discovery operation?
   YES → Use search tools (search_and_geocode, category_search)

Key Decision Questions

1. Does "distance" mean as the crow flies or as the crow drives?
   • As the crow flies (straight-line) → geometric tools
   • As the crow drives (road distance) → routing APIs
2. Does the user need travel time?
   • Yes → routing APIs (only they know speeds/traffic)
   • No → geometric tools may suffice
3. Is this about roads/paths or pure spatial relationships?
   • Roads/paths → routing APIs
   • Spatial relationships → geometric tools
4. Does this need to happen in real-time with low latency?
   • Yes + geometric problem → offline tools (instant)
   • Yes + routing problem → use routing APIs (still fast)
5. Is accuracy critical, or is approximation OK?
   • Critical + routing → routing APIs
   • Approximation OK → geometric tools may work

Terminology Guide

Quick Reference

Geometric Operations (Offline Tools)

• distance_tool

  - Straight-line distance between two points

• bearing_tool

  - Compass direction from A to B

• midpoint_tool

  - Midpoint between two points

• point_in_polygon_tool

  - Is point inside polygon?

• area_tool

  - Calculate polygon area

• buffer_tool

  - Create circular buffer/zone

• centroid_tool

  - Geometric center of polygon

• bbox_tool

  - Min/max coordinates of geometry

• simplify_tool

  - Reduce geometry complexity

Routing & Navigation (APIs)

• directions_tool

  - Turn-by-turn routing

• matrix_tool

  - Many-to-many travel times

• optimization_tool

  - Route optimization (TSP)

• isochrone_tool

  - Travel-time zones

• map_matching_tool

  - Snap GPS to roads

When to Use Each Category

• Problem is spatial/mathematical (containment, area, bearing)
• Straight-line distance is appropriate
• Need instant results for real-time checks
• Pure geometry (no roads/traffic involved)

• Need actual driving/walking/cycling distances
• Need travel times
• Need to consider road networks
• Need traffic awareness
• Need route optimization
• Need turn-by-turn directions

Integration with Other Skills

• mapbox-search-patterns: Search for locations, then use geospatial operations
• mapbox-web-performance-patterns: Optimize rendering of geometric calculations
• mapbox-token-security: Ensure requests use properly scoped tokens

Resources

• Mapbox MCP Server
• Turf.js Documentation (Powers geometric tools)
• Mapbox Directions API
• Mapbox Isochrone API
• Mapbox Matrix API
• Mapbox Optimization API