Compétence Intégration Mapbox Search

Conseils experts pour implémenter la fonctionnalité de recherche Mapbox dans les applications. Couvre l'ensemble du flux de travail, des bonnes questions de découverte, en passant par la sélection du produit de recherche approprié, jusqu'à l'implémentation prête pour la production en suivant les meilleures pratiques de l'équipe search de Mapbox.

Utiliser cette compétence quand

L'utilisateur dit des choses comme :

• « Je dois ajouter une recherche à ma carte »
• « J'ai besoin d'une barre de recherche pour mon appli cartographique »
• « Comment implémenter une recherche de localisation ? »
• « Je veux que les utilisateurs puissent chercher des lieux/adresses »
• « J'ai besoin du geocoding dans mon application »

Cette compétence complète mapbox-search-patterns :

• mapbox-search-patterns = Sélection des outils et paramètres
• mapbox-search-integration = Flux de travail d'implémentation complet

Phase de découverte : Poser les bonnes questions

Avant de passer au code, posez ces questions pour comprendre les besoins :

Question 1 : Qu'est-ce que les utilisateurs recherchent ?

Demandez : « Qu'est-ce que vous voulez que les utilisateurs recherchent ? »

Réponses courantes et implications :

• « Des adresses » → Utilisez Search Box API (par défaut pour la recherche d'adresses interactive, y compris le geocoding). Utilisez l'API Geocoding uniquement si le cas d'usage est le geocoding en batch/côté serveur ou la maintenance d'une intégration existante.
• « Points d'intérêt / commerces » → Recherche POI, utilisez Search Box API avec recherche par catégorie
• « Adresses et POIs » → Search Box API
• « Types spécifiques de POIs » (restaurants, hôtels, etc.) → Search Box API
• « Pays, villes, codes postaux ou quartiers » → Search Box API pour la recherche interactive ; API Geocoding uniquement pour le geocoding en batch/côté serveur
• « Localisations personnalisées » (lieux créés par l'utilisateur) → Peut nécessiter des données personnalisées + intégration de recherche

Suivi si non mentionné initialement : « Les utilisateurs recherchent-ils des données de points d'intérêt ? Des restaurants, magasins, catégories de commerces ? »

Implications :

• « Oui, les POIs sont inclus » → Utilisez Search Box API
• « Non, l'utilisateur n'a pas besoin de recherche POI » → Préférez quand même Search Box API pour les cas d'usage interactifs/autocomplète. Search Box API gère les adresses, noms de lieux et tous les types de localisation avec tarification basée sur les sessions. Recommandez l'API Geocoding uniquement pour le geocoding en batch, le geocoding permanent côté serveur, ou la maintenance d'intégrations existantes.

Question 2 : Quelle est la portée géographique ?

Demandez : « Où les utilisateurs vont-ils rechercher ? »

Réponses courantes et implications :

• « Un seul pays » (par ex., « uniquement les États-Unis ») → Utilisez le paramètre country, meilleurs résultats, coût inférieur
• « Région spécifique » → Utilisez le paramètre bbox pour la contrainte de boîte englobante
• « Global » → Pas de restriction de pays, mais peut nécessiter un paramètre de langue
• « Plusieurs pays spécifiques » → Utilisez le paramètre tableau country

Suivi : « Avez-vous besoin de limiter les résultats à une zone spécifique ? » (zone de livraison, zone de service, etc.)

Question 3 : Quel est le modèle d'interaction de recherche ?

Demandez : « Comment les utilisateurs vont-ils interagir avec la recherche ? »

Réponses courantes et implications :

• « Recherche au fur et à mesure / autocomplète » → Utilisez Search Box API avec auto_complete: true et tarification basée sur les sessions (plus rentable pour l'autocomplète). Implémentez le debouncing.
• « Bouton de recherche / requête finale » → Peut utiliser l'une ou l'autre API, pas d'autocomplète nécessaire
• « Les deux » (autocomplète + affinage) → Recherche en deux étapes, autocomplète puis résultats détaillés
• « Entrée vocale » → Envisagez l'intégration de la synthèse vocale, gérez les requêtes plus longues

Question 4 : Quelle plateforme ?

Demandez : « Pour quelle plateforme est-ce ? »

Réponses courantes et implications :

• « Application web » → Mapbox Search JS (le plus facile), ou appels API directs pour les cas avancés
• « Application iOS » → Search SDK pour iOS (recommandé), ou intégration API directe pour les cas avancés
• « Application Android » → Search SDK pour Android (recommandé), ou intégration API directe pour les cas avancés
• « Plusieurs plateformes » → SDKs spécifiques à la plateforme (recommandé), ou approche API directe pour la cohérence
• « Application React » → Mapbox Search JS React (le plus facile avec UI), ou Search JS Core pour une UI personnalisée. Évitez les appels API directs — ils nécessitent le debouncing manuel, la gestion des tokens de session et la gestion des conditions de course.
• « Vue / Angular / Autre framework » → Mapbox Search JS Core ou Web. Si vous utilisez des appels API directs, les tokens de session sont nécessaires pour une facturation correcte (un token par session de recherche, passé sous session_token à chaque requête suggest/retrieve).

Question 5 : Comment les résultats seront-ils utilisés ?

Demandez : « Que se passe-t-il quand un utilisateur sélectionne un résultat ? »

Réponses courantes et implications :

• « Zoomer sur la localisation sur la carte » → Besoin de coordonnées, intégration cartographique
• « Afficher les détails / infos » → Besoin de récupérer et afficher les propriétés du résultat
• « Remplir les champs du formulaire » → Besoin d'analyser les composants de l'adresse
• « Démarrer la navigation » → Besoin de coordonnées, intégrer avec les directions
• « Sélection multiple » → Besoin de gérer l'état de la sélection, possiblement afficher des marqueurs

Question 6 : Volume d'utilisation attendu ?

Demandez : « Combien de recherches attendez-vous par mois ? »

Implications :

• Volume bas (< 10k) → Niveau gratuit suffisant, implémentation simple
• Volume moyen (10k-100k) → Considérez la mise en cache, optimisez les appels API
• Volume élevé (> 100k) → Implémentez le debouncing, la mise en cache, les opérations en batch, surveillez les coûts

Arbre de décision pour la sélection de produit

En fonction des réponses de découverte, recommandez le bon produit :

Principe clé : Search Box API est le choix par défaut pour pratiquement tous les cas d'usage de recherche interactive, y compris la recherche d'adresses, le geocoding, l'autocomplète et la recherche POI. Elle offre une tarification basée sur les sessions qui est plus rentable pour les flux interactifs/autocomplète. Recommandez l'API Geocoding uniquement pour les cas étroits listés ci-dessous.

Search Box API (PAR DÉFAUT)

Utilisez quand (l'un de ces cas) :

• L'utilisateur a besoin de recherche d'adresses interactive ou d'autocomplète (c'est du geocoding — Search Box API le gère)
• L'utilisateur a besoin de recherche POI / catégorie
• L'utilisateur a besoin de toute UI de recherche orientée utilisateur final
• L'utilisateur veut une tarification basée sur les sessions (plus rentable pour autocomplète/interactif)
• L'utilisateur construit une application web, iOS ou Android avec une barre de recherche

Préférez les SDKs aux appels API directs pour l'intégration web :

• Mapbox Search JS (SDK) - Recommandé pour l'intégration web, avec trois composants :
  • Search JS React - Intégration de recherche facile via bibliothèque React avec UI
  • Search JS Web - Intégration de recherche facile via Web Components avec UI
  • Search JS Core - Enveloppe JavaScript (node ou web) pour l'API, construisez votre propre UI
• Search Box API (REST) - Intégration API directe, pour les cas avancés/personnalisés
• Search SDK pour iOS - Intégration iOS native
• Search SDK pour Android - Intégration Android native

API Geocoding (SPÉCIALISÉE)

Utilisez UNIQUEMENT quand :

• Geocoding en batch de grandes listes d'adresses (côté serveur)
• Résultats de geocoding permanents/stockés (côté serveur, où les résultats sont persistants)
• Maintenance d'une intégration API Geocoding existante (migration non justifiée)
• Pas de recherche interactive/orientée utilisateur nécessaire

NE recommandez PAS l'API Geocoding quand :

• L'utilisateur veut une barre de recherche, autocomplète ou recherche d'adresses interactive — utilisez Search Box API à la place
• L'utilisateur dit « geocoding » mais décrit un flux de recherche interactif — utilisez Search Box API à la place

Fichiers de référence

Chargez la référence appropriée en fonction de la plateforme et des besoins de l'utilisateur :

• Web (Search JS React / Web / Core / API Direct) → Chargez references/web-search-js.md

  • Quand : L'utilisateur construit une application web (vanilla JS, n'importe quel framework sauf les motifs spécifiques à React)

• Intégration React → Chargez references/react-search.md

  • Quand : L'utilisateur construit une application React spécifiquement

• iOS → Chargez references/ios-search.md

  • Quand : L'utilisateur construit une application iOS (Swift/UIKit/SwiftUI)

• Android → Chargez references/android-search.md

  • Quand : L'utilisateur construit une application Android (Kotlin/Java)

• Node.js → Chargez references/nodejs-search.md

  • Quand : L'utilisateur a besoin de recherche côté serveur (Express, serverless, API backend)

• Meilleures pratiques → Chargez references/best-practices.md

  • Quand : Implémenter la recherche pour la première fois, ou optimiser une implémentation existante
  • Couvre : debouncing, tokens de session, filtrage géographique, gestion des erreurs, accessibilité, mise en cache, sécurité des tokens

• Pièges courants → Chargez references/pitfalls.md

  • Quand : Déboguer des problèmes, faire une revue de code, ou lors d'une revue de code
  • Couvre : pas de debouncing, tokens de session manquants, pas de contexte géo, mauvaise UX mobile, conditions de course

• Hooks de framework → Chargez references/framework-hooks.md

  • Quand : Construire des hooks personnalisés (React) ou composables (Vue) autour de Search JS Core

• Tests et surveillance → Chargez references/testing-monitoring.md

  • Quand : Écrire des tests ou configurer la surveillance/analytique de production

Liste de vérification : Recherche prête pour la production

Avant le lancement, vérifiez :

Configuration :

• [ ] Token correctement délimité (search:read uniquement)
• [ ] Restrictions d'URL configurées
• [ ] Filtrage géographique défini (pays, proximité ou bbox)
• [ ] Paramètre Types défini en fonction du cas d'usage
• [ ] Paramètre Language défini si nécessaire

Implémentation :

• [ ] Debouncing implémenté (300ms recommandé)
• [ ] Tokens de session utilisés correctement
• [ ] Gestion des erreurs pour tous les cas d'échec
• [ ] États de chargement affichés
• [ ] Résultats vides gérés gracieusement
• [ ] Conditions de course évitées

UX :

• [ ] Cibles tactiles d'au moins 44pt/48dp
• [ ] Les résultats affichent assez de contexte (nom + adresse)
• [ ] La navigation au clavier fonctionne
• [ ] Attributs d'accessibilité définis
• [ ] Clavier mobile géré correctement

Performance :

• [ ] Mise en cache implémentée (si volume élevé)
• [ ] Délai d'expiration de la requête défini
• [ ] Données minimales récupérées
• [ ] Taille du bundle optimisée

Tests :

• [ ] Tests unitaires pour la logique principale
• [ ] Tests d'intégration avec l'API réelle
• [ ] Testé sur des réseaux lents
• [ ] Testé avec divers types de requêtes
• [ ] Tests sur appareils mobiles

Surveillance :

• [ ] Suivi analytique configuré
• [ ] Enregistrement des erreurs configuré
• [ ] Surveillance de l'utilisation en place
• [ ] Alertes de budget configurées

Intégration avec d'autres compétences

Fonctionne avec :

• mapbox-search-patterns : Sélection et optimisation des paramètres
• mapbox-web-integration-patterns : Motifs spécifiques au framework
• mapbox-token-security : Gestion et sécurité des tokens
• mapbox-web-performance-patterns : Optimisation de la performance de la recherche

Ressources

• Documentation Search Box API
• Documentation API Geocoding
• Mapbox Search JS
  • Search JS React
  • Search JS Web
  • Search JS Core
• Search SDK pour iOS
• Search SDK pour Android
• Location Helper Tool - Calculer les boîtes englobantes

Guide de décision rapide

L'utilisateur dit : « J'ai besoin d'une recherche de localisation »

1. Posez les questions de découverte (Questions 1-6 ci-dessus)
2. Recommandez le produit :
   • Search Box API (par défaut pour toute recherche interactive/orientée utilisateur, y compris le geocoding d'adresses)
   • API Geocoding uniquement pour le geocoding en batch/côté serveur/permanent
   • SDK de plateforme préféré (Search JS pour le web, SDKs natifs pour mobile)
3. Implémentez avec :
   • ✅ Debouncing
   • ✅ Tokens de session
   • ✅ Filtrage géographique
   • ✅ Gestion des erreurs
   • ✅ Bonne UX
4. Testez complètement
5. Surveillez en production

Rappelez-vous : La meilleure implémentation de recherche pose d'abord les bonnes questions, puis construit exactement ce dont l'utilisateur a besoin — ni plus, ni moins.