Compétence de Motifs de Recherche Mapbox

Guidance d'expert pour les assistants IA sur l'utilisation efficace des outils de recherche Mapbox. Couvre la sélection des outils, l'optimisation des paramètres et les bonnes pratiques pour le géocodage, la recherche de POI et la découverte de lieux.

Outils de Recherche Disponibles

1. search_and_geocode_tool

Idéal pour : Lieux spécifiques, adresses, marques, emplacements nommés

À utiliser quand la requête contient :

• Noms spécifiques : « Starbucks on 5th Avenue », « Empire State Building »
• Noms de marques : « McDonald's », « Whole Foods »
• Adresses : « 123 Main Street, Seattle », « 1 Times Square »
• Chaînes de magasins : « Target »
• Villes/lieux : « San Francisco », « Portland »

À ne pas utiliser pour : Catégories génériques (« coffee shops », « museums »)

2. category_search_tool

Idéal pour : Types de lieux génériques, catégories, requêtes au pluriel

À utiliser quand la requête contient :

• Types génériques : « coffee shops », « restaurants », « gas stations »
• Formes plurielles : « museums », « hotels », « parks »
• Phrases du type is-a : « any coffee shop », « all restaurants », « nearby pharmacies »
• Termes sectoriels : « electric vehicle chargers », « ATMs »

À ne pas utiliser pour : Noms spécifiques ou marques

3. reverse_geocode_tool

Idéal pour : Convertir des coordonnées en adresses, villes, localités, codes postaux

À utiliser quand :

• Vous avez des coordonnées GPS, vous avez besoin d'une adresse lisible par l'humain
• Vous devez identifier ce qui se trouve à un endroit spécifique
• Convertir la localisation de l'utilisateur en adresse

Matrice de Décision de Sélection des Outils

Guidance des Paramètres

Proximity vs Bbox vs Country

Trois façons de contraindre spatialement les résultats de recherche :

1. proximity (FORTEMENT RECOMMANDÉ)

Ce qu'elle fait : Privilégie les résultats près d'un lieu, mais n'exclut pas les correspondances lointaines

À utiliser quand :

• L'utilisateur dit « near me », « nearby », « close to »
• Vous avez un point de référence mais voulez une certaine flexibilité
• Vous voulez que les résultats soient triés par pertinence par rapport à un point

Exemple :

{
  "q": "pizza",
  "proximity": {
    "longitude": -122.4194,
    "latitude": 37.7749
  }
}

Pourquoi ça marche : L'API retourne d'abord les pizzerias de SF, mais peut inclure des pizzerias célèbres de NYC si elles sont très pertinentes

Critique : Définissez toujours proximity quand vous avez une localisation de référence ! Sans cela, les résultats sont basés sur l'IP ou globaux.

2. bbox (Bounding Box)

Ce qu'elle fait : Contrainte dure - retourne UNIQUEMENT les résultats dans la boîte

À utiliser quand :

• L'utilisateur spécifie une zone : « in downtown », « within this neighborhood »
• Vous avez une zone de service définie
• Vous devez garantir que les résultats se trouvent dans les limites

Exemple :

{
  "q": "hotel",
  "bbox": [-122.51, 37.7, -122.35, 37.83] // [minLon, minLat, maxLon, maxLat]
}

Pourquoi ça marche : Garantit que tous les hôtels sont dans la zone downtown de SF

Attention : Trop petit = pas de résultats ; trop grand = résultats non pertinents

3. country

Ce qu'elle fait : Limite les résultats à des pays spécifiques

À utiliser quand :

• L'utilisateur spécifie un pays : « restaurants in France »
• Vous construisez des fonctionnalités spécifiques à un pays
• Vous devez respecter les frontières régionales
• Ou il est sinon clair qu'ils veulent des résultats dans un pays spécifique

Exemple :

{
  "q": "Paris",
  "country": ["FR"] // Codes ISO 3166 alpha-2
}

Pourquoi ça marche : Trouve Paris, France (pas Paris, Texas)

Peut combiner : proximity + country + bbox ou toute combinaison des trois

Matrice de Décision : Filtres Spatiaux

Paramètre limit

category_search_tool uniquement (1-25, par défaut 10)

Conseil de performance : Des limites plus basses = réponses plus rapides

Paramètre types (search_and_geocode_tool)

Filtrer par type de feature :

Combinaisons d'exemples :

// Uniquement POI et adresses, pas de villes
{"q": "Paris", "types": ["poi", "address"]}
// Retourne Paris Hotel, Paris Street, pas Paris, France

// Uniquement les places (villes)
{"q": "Paris", "types": ["place"]}
// Retourne Paris, France; Paris, Texas; etc.

Comportement par défaut : Tous les types inclus (généralement ce que vous voulez)

Paramètre auto_complete (search_and_geocode_tool)

Ce qu'il fait : Active la correspondance partielle/floue

Exemple :

// L'utilisateur tape "starb"
{ "q": "starb", "auto_complete": true }
// Retourne : Starbucks, Starboard Tavern, etc.

À utiliser pour :

• Interfaces search-as-you-type
• Gérer les fautes de frappe (« mcdonalds » -> McDonald's)
• Requêtes incomplètes

À ne pas utiliser pour :

• Requêtes finales/soumises (moins précis)
• Quand vous avez besoin de correspondances exactes

Anti-motifs à Éviter

À ne pas faire : Utiliser category_search pour les marques

// MAUVAIS
category_search_tool({ category: 'starbucks' });
// « starbucks » n'est pas une catégorie, retourne une erreur

// BON
search_and_geocode_tool({ q: 'Starbucks' });

À ne pas faire : Utiliser search_and_geocode pour les catégories génériques

// MAUVAIS
search_and_geocode_tool({ q: 'coffee shops' });
// Moins précis, peut retourner des résultats non pertinents

// BON
category_search_tool({ category: 'coffee_shop' });

À ne pas faire : Oublier proximity pour les recherches locales

// MAUVAIS - Les résultats peuvent être n'importe où dans le monde
category_search_tool({ category: 'restaurant' });

// BON - Privilégié vers la localisation de l'utilisateur
category_search_tool({
  category: 'restaurant',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

À ne pas faire : Utiliser bbox quand vous voulez dire proximity

// MAUVAIS - La frontière dure peut exclure de bons résultats à proximité
search_and_geocode_tool({
  q: 'pizza',
  bbox: [-122.42, 37.77, -122.41, 37.78] // Boîte minuscule
});

// BON - Privilégier un point, mais flexible
search_and_geocode_tool({
  q: 'pizza',
  proximity: { longitude: -122.4194, latitude: 37.7749 }
});

À ne pas faire : Demander l'ETA inutilement

// MAUVAIS - Coûte le quota API pour les calculs de routage
search_and_geocode_tool({
  q: 'museums',
  eta_type: 'navigation',
  navigation_profile: 'driving'
});
// L'utilisateur n'a pas demandé le temps de trajet !

// BON - Ajouter l'ETA uniquement si nécessaire
search_and_geocode_tool({ q: 'museums' });
// Si l'utilisateur demande « how long to get there? », alors ajouter l'ETA

À ne pas faire : Définir limit trop haut pour l'affichage UI

// MAUVAIS - Accablant pour un simple dropdown
category_search_tool({
  category: 'restaurant',
  limit: 25
});
// Retourne 25 restaurants pour un dropdown de 5 éléments

// BON - Adapter aux besoins de l'interface
category_search_tool({
  category: 'restaurant',
  limit: 5
});

Référence Rapide

Organigramme de Sélection d'Outil

La requête utilisateur contient...

-> Nom/marque spécifique (Starbucks, Empire State Building)
  -> search_and_geocode_tool

-> Catégorie générique/pluriel (coffee shops, museums, any restaurant)
  -> category_search_tool

-> Coordonnées -> Adresse
  -> reverse_geocode_tool

-> Adresse -> Coordonnées
  -> search_and_geocode_tool avec types: ["address"]

Checklist des Paramètres Essentiels

Pour les recherches locales, TOUJOURS définir :

• proximity (ou bbox si frontière stricte nécessaire)

Pour les recherches de catégories, considérer :

• limit (adapter aux besoins de l'interface)
• format (json_string si tracer sur une carte)

Pour la désambiguïsation, utiliser :

• country (quand le contexte géographique compte)
• types (quand le type de feature compte)

Pour le classement par temps de trajet :

• eta_type, navigation_profile, origin (coûte le quota API)

Erreurs Courantes

1. Oublier proximity -> Les résultats sont globaux/basés sur l'IP
2. Utiliser le mauvais outil -> category_search pour « Starbucks » (utiliser search_and_geocode)
3. Catégorie invalide -> Vérifier d'abord la category_list
4. Bbox trop petit -> Pas de résultats ; utiliser proximity à la place
5. Demander l'ETA inutilement -> Ajoute le coût API
6. Limit trop haut pour l'interface -> Accablant pour l'utilisateur
7. Ne pas filtrer types -> Obtenir des villes quand vous voulez des POI

Fichiers de Référence

Charger ceux-ci pour une guidance plus approfondie sur des sujets spécifiques :

• references/advanced-params.md — poi_category, ETA, format et paramètres de langue
• references/workflows.md — Motifs courants : Near Me, Branded, Geocoding, Category+Area, Reverse, Route-Based, Multilingual
• references/optimization-combining.md — Optimisation de performance, combinaison d'outils, gestion des résultats vides, ressource de liste de catégories