Compétence Opérations Géospatiales Mapbox

Guidance d'expert pour les assistants IA sur le choix des bons outils géospatiaux du serveur MCP Mapbox. Se concentre sur la sélection d'outils basée sur ce que le problème exige - calculs géométriques vs routage, ligne droite vs réseau routier, et besoins en précision.

Principe Central : Le Type de Problème Détermine le Choix de l'Outil

Le serveur MCP Mapbox fournit deux catégories d'outils géospatiaux :

1. Outils Géométriques Hors Ligne - Utiliser Turf.js pour les calculs géométriques/spatiaux purs
2. APIs de Routage et Navigation - Utiliser les APIs Mapbox quand vous avez besoin de routage réel, trafic ou temps de trajet

La question clé : Que le problème exige-t-il vraiment ?

Cadre de Décision

Matrices de Décision par Cas d'Usage

Calculs de Distance

L'utilisateur demande : "Quelle est la distance entre X et Y ?"

Exemple : "Quelle est la distance entre ces 5 entrepôts ?"

• À vol d'oiseau → distance_tool (10 calculs, instantané)
• Comme en voiture → matrix_tool (matrice 5×5, un appel API, retourne distances réelles)

Insight clé : Utiliser l'outil qui correspond à ce que "distance" signifie dans le contexte. Toujours clarifier : à vol d'oiseau ou comme en voiture ?

Proximité et Containment

L'utilisateur demande : "Quels points sont proches/à l'intérieur de cette zone ?"

Exemple : "Ces 200 adresses sont-elles dans notre zone de livraison de 30 minutes ?"

1. Créer zone → isochrone_tool (API routage - besoin temps de trajet)
2. Vérifier adresses → point_in_polygon_tool (géométrique - 200 vérifications instantanées)

Insight clé : Routage pour créer zones temps de trajet, géométrique pour vérifications containment

Routage et Navigation

L'utilisateur demande : "Quel est le meilleur itinéraire ?"

Exemple : "Naviguer depuis l'hôtel jusqu'à l'aéroport"

• Besoin virage par virage → directions_tool
• Juste besoin savoir "c'est au nord-est" → bearing_tool

Insight clé : Outils routage pour navigation réelle, outils géométriques pour info directionnelle

Opérations de Zone et Forme

L'utilisateur demande : "Créer une zone autour de ce lieu"

Exemple : "Montrer couverture 5km autour de chaque magasin"

• Rayon 5km → buffer_tool (cercles géométriques)
• "Quels clients peuvent accéder en 15 min ?" → isochrone_tool (basé routage)

Insight clé : Outils géométriques pour zones basées distance, outils routage pour zones basées temps

Considérations de Performance et Échelle

Quand le Volume Affecte le Choix d'Outil

Petites opérations (< 100 calculs) :

• Outils géométriques : Instantané, itérer librement
• APIs routage : Assez rapide pour la plupart des utilisations

Opérations moyennes (100-1 000 calculs) :

• Outils géométriques : Toujours rapides, pas de préoccupations
• APIs routage : Considérer opérations batch (matrix_tool)

Grandes opérations (> 1 000 calculs) :

• Outils géométriques : Peut nécessiter optimisation mais toujours rapides
• APIs routage : Utiliser définitivement outils batch (matrix_tool gère jusqu'à 25×25)

Insight clé : Volume affecte rarement choix outil géométrique, mais APIs routage ont outils batch pour efficacité

Temps Réel vs Batch

Note architecture pour géofencing haute fréquence : Si l'application appelle vérifications containment à très haute fréquence (ex : 50 véhicules toutes les 2 secondes = 25 vérifications/seconde), appeler outils MCP sur le réseau ajoute overhead raisonnement agent rendant impratique. Dans ces cas, recommander utiliser Turf.js directement en-process (turf.booleanPointInPolygon) pour le chemin critique, et réserver outils MCP pour tâches périphériques comme définition zone (isochrone_tool), reroutage (directions_tool), ou visualisation (static_map_image_tool).

Scénarios Courants et Approches Optimales

Scénario 1 : Localiseur de Magasin

Utilisateur : "Trouver le magasin le plus proche et montrer couverture 5km"

Approche optimale :

1. Chercher magasins → category_search_tool (retourne distances automatiquement)
2. Créer zone couverture → buffer_tool (cercle géométrique 5km)
3. Visualiser → static_map_image_tool

Pourquoi : Recherche donne déjà distances ; buffer géométrique pour rayon simple

Scénario 2 : Optimisation Route de Livraison

Utilisateur : "Optimiser livraison à 8 adresses/arrêts"

Approche optimale :

1. Géocoder adresses (si nécessaire) → Utiliser search_and_geocode_tool pour convertir adresses en coordonnées. Même quand coordonnées déjà fournies, mentionner comme étape optionnelle pré-routage — listes livraison réelles contiennent souvent mélange adresses et coordonnées.
2. Optimiser route → optimization_tool (solveur TSP — réordonne arrêts pour minimiser temps conduite total)

Pourquoi optimization_tool et NON ces alternatives :

• directions_tool route seulement A → B (ou via waypoints ordre fixe). Ne réordonne PAS arrêts — si vous passez 8 arrêts, il les route dans l'ordre donné, ce qui est presque jamais optimal.
• matrix_tool donne temps trajet entre toutes paires d'arrêts (8×8 = 64 valeurs), mais ne calcule PAS l'ordre optimal. Vous auriez besoin résoudre TSP vous-même sur la matrice — optimization_tool fait ça pour vous en un appel.

Toujours mentionner search_and_geocode_tool comme compagnon utile pour géocoder adresses livraison avant optimisation.

Scénario 3 : Validation Zone de Service

Utilisateur : "Lesquelles de ces 200 adresses peuvent nous livrer en 30 minutes ?"

Approche optimale :

1. Créer zone livraison → isochrone_tool (30 minutes voiture)
2. Vérifier chaque adresse → point_in_polygon_tool (200 vérifications géométriques)

Pourquoi : Routage pour zone temps de trajet précise, géométrique pour vérifications containment rapides

Scénario 4 : Analyse Trace GPS

Utilisateur : "Quelle a été la durée de ce trajet à vélo ?"

Approche optimale :

1. Nettoyer trace GPS → map_matching_tool (accrocher aux pistes vélo)
2. Obtenir distance → Utiliser réponse API ou calculer avec distance_tool

Pourquoi : Besoin accrochage route/chemin ; calcul distance fonctionne de toute façon

Scénario 5 : Analyse Couverture

Utilisateur : "Quelle est notre zone de service totale ?"

Approche optimale :

1. Créer buffers autour chaque lieu → buffer_tool
2. Calculer aire totale → area_tool
3. Ou, si basé temps → isochrone_tool pour chaque lieu

Pourquoi : Géométrique pour couverture distance, routage pour basée temps

Anti-Patterns : Utiliser le Mauvais Type d'Outil

❌ Ne pas : Utiliser outils géométriques pour questions routage

// FAUX : L'utilisateur demande "combien de temps pour conduire là ?"
distance_tool({ from: A, to: B });
// Retourne 10km à vol d'oiseau, mais vraie route est 15km

// CORRECT : Besoin routage pour distance voiture
directions_tool({
  coordinates: [
    { longitude: A[0], latitude: A[1] },
    { longitude: B[0], latitude: B[1] }
  ],
  routing_profile: 'mapbox/driving'
});
// Retourne vraie distance route et temps voiture comme en voiture

Pourquoi faux : À vol d'oiseau ≠ comme en voiture

❌ Ne pas : Utiliser APIs routage pour opérations géométriques

// FAUX : Vérifier si point dans polygon
// (Impossible avec APIs routage)

// CORRECT : Opération géométrique pure
point_in_polygon_tool({ point: location, polygon: boundary });

Pourquoi faux : APIs routage ne font pas containment géométrique

❌ Ne pas : Confondre "proche" avec "accessible"

// L'utilisateur demande : "Qu'est-ce accessible en 20 minutes ?"

// FAUX : 20 minutes distance à vitesse moyenne
distance_tool + calculate 20min * avg_speed

// CORRECT : Vrai routage avec réseau routier
isochrone_tool({
  coordinates: {longitude: startLng, latitude: startLat},
  contours_minutes: [20],
  profile: "mapbox/driving"
})

Pourquoi faux : Routes ne sont pas lignes droites ; trafic varie

❌ Ne pas : Utiliser routage quand direction suffit

// L'utilisateur demande : "Dans quelle direction est l'aéroport ?"

// SURCOMPLIQU'E : Routage complet
directions_tool({
  coordinates: [
    { longitude: hotel[0], latitude: hotel[1] },
    { longitude: airport[0], latitude: airport[1] }
  ]
});

// MIEUX : Juste besoin direction
bearing_tool({ from: hotel, to: airport });
// Retourne : "Nord-Est (45°)"

Pourquoi mieux : Plus simple, instantané, répond question réelle

Approches Hybrides : Combiner Types d'Outils

Certains problèmes bénéficient d'utiliser outils géométriques et routage :

Pattern 1 : Routage + Filtre Géométrique

1. directions_tool → Obtenir géométrie route
2. buffer_tool → Créer corridor autour route
3. category_search_tool → Trouver POIs dans corridor
4. point_in_polygon_tool → Filtrer à ceux vraiment sur route

Cas d'usage : "Trouver stations essence sur mon itinéraire"

Pattern 2 : Routage + Calcul Distance

1. category_search_tool → Trouver 10 lieux proches
2. distance_tool → Calculer distances ligne droite (géométrique)
3. Pour top 3, utiliser directions_tool → Obtenir temps voiture réel

Cas d'usage : Réduire rapidement, puis obtenir routage précis pour finalistes

Pattern 3 : Isochrone + Containment

1. isochrone_tool → Créer zone temps de trajet (routage)
2. point_in_polygon_tool → Vérifier centaines d'adresses (géométrique)

Cas d'usage : "Quels clients sont dans notre zone livraison ?"

Algorithme de Décision

Quand l'utilisateur pose question géospatiale :

1. Nécessite-t-il routage, routes, ou temps trajet ?
   OUI → Utiliser API routage (directions, matrix, isochrone, optimization)
   NON → Continuer

2. Nécessite-t-il awareness trafic ?
   OUI → Utiliser directions_tool ou isochrone_tool avec profil trafic
   NON → Continuer

3. Est-ce opération géométrique/spatiale ?
   - Distance entre points (ligne droite) → distance_tool
   - Containment points → point_in_polygon_tool
   - Calcul aire → area_tool
   - Buffer/zone → buffer_tool
   - Direction/bearing → bearing_tool
   - Centre géométrique → centroid_tool
   - Boîte englobante → bounding_box_tool
   - Simplification → simplify_tool

4. Est-ce opération recherche/découverte ?
   OUI → Utiliser outils recherche (search_and_geocode, category_search)

Questions de Décision Clés

Avant choisir outil, demander :

1. "Distance" signifie-t-il à vol d'oiseau ou comme en voiture ?

   • À vol d'oiseau (ligne droite) → outils géométriques
   • Comme en voiture (distance route) → APIs routage

2. L'utilisateur a-t-il besoin temps trajet ?

   • Oui → APIs routage (seules connaissent vitesses/trafic)
   • Non → outils géométriques peuvent suffire

3. Est-ce à propos routes/chemins ou relations spatiales pures ?

   • Routes/chemins → APIs routage
   • Relations spatiales → outils géométriques

4. Doit-ce arriver en temps réel avec faible latence ?

   • Oui + problème géométrique → outils hors ligne (instantané)
   • Oui + problème routage → utiliser APIs routage (toujours rapide)

5. La précision est-elle critique, ou approximation OK ?

   • Critique + routage → APIs routage
   • Approximation OK → outils géométriques peuvent fonctionner

Guide Terminologie

Comprendre ce que les utilisateurs veulent dire :

Référence Rapide

Opérations Géométriques (Outils Hors Ligne)

• distance_tool - Distance ligne droite entre deux points
• bearing_tool - Direction compas de A à B
• midpoint_tool - Point milieu entre deux points
• point_in_polygon_tool - Point est-il dans polygon ?
• area_tool - Calculer aire polygon
• buffer_tool - Créer buffer/zone circulaire
• centroid_tool - Centre géométrique polygon
• bbox_tool - Coordonnées min/max géométrie
• simplify_tool - Réduire complexité géométrie

Routage & Navigation (APIs)

• directions_tool - Routage virage par virage
• matrix_tool - Temps trajet plusieurs-à-plusieurs
• optimization_tool - Optimisation route (TSP)
• isochrone_tool - Zones temps de trajet
• map_matching_tool - Accrocher GPS à routes

Quand Utiliser Chaque Catégorie

Utiliser Outils Géométriques Quand :

• Problème spatial/mathématique (containment, aire, bearing)
• Distance ligne droite est appropriée
• Besoin résultats instantanés pour vérifications temps réel
• Géométrie pure (routes/trafic pas impliqués)

Utiliser APIs Routage Quand :

• Besoin distances voiture/marche/vélo réelles
• Besoin temps trajet
• Besoin considérer réseaux routiers
• Besoin awareness trafic
• Besoin optimisation route
• Besoin directions virage par virage

Intégration avec Autres Compétences

Fonctionne avec :

• mapbox-search-patterns : Chercher lieux, puis utiliser opérations géospatiales
• mapbox-web-performance-patterns : Optimiser rendu calculs géométriques
• mapbox-token-security : Assurer requêtes utilisent tokens portée appropriée

Ressources

• Serveur MCP Mapbox
• Documentation Turf.js (Alimente outils géométriques)
• API Directions Mapbox
• API Isochrone Mapbox
• API Matrix Mapbox
• API Optimization Mapbox