Migrer les API Azure Maps Recherche 1.0

Rechercher L’API version 2026-01-01 remplace l’API de recherche version 1.0. La version plus récente introduit des points de terminaison spécifiques aux tâches, une intention plus claire et une scalabilité améliorée. Cet article explique comment migrer des intégrations de recherche v1 existantes.

Important

L’API Recherche Azure Maps version 1.0 a été remplacée par l’API De recherche version 2026-01-01. Bien que Search v1 continue de fonctionner, tout nouveau développement doit utiliser la dernière API de recherche pour accéder aux points de terminaison spécifiques aux tâches, pour améliorer les performances et bénéficier d'un support à long terme. Pour éviter les interruptions de service futures, migrez les intégrations de Recherche v1 existantes vers Search 2026-01-01.

Mappage d’équivalence d’API

Objectif API De recherche v1 Rechercher 2026‑01‑01 API
Géocodage direct Obtenir l’adresse de recherche Get Geocoding
Adresse Get Search Fuzzy (final) Get Geocoding
Autocomplétion Get Search Fuzzy (saisie anticipée) Obtenir la fonction d'auto-complétion du géocode
Géocodage par lot Get Search Address Batch Get Geocoding Batch
Géocodage inverse Obtenir l’adresse de recherche inversée Obtenir le géocodage inverse
Batch reverse Get Search Address Reverse Batch Get Reverse Geocoding Batch
Boundaries Obtenir un polygone de recherche Obtenir polygone

Différences notables

Les API Search 2026-01-01 introduisent des points de terminaison spécifiques à l’intention, une sémantique de requête plus claire et un comportement de résultat plus strict par rapport à la recherche v1. Le tableau suivant récapitule les différences les plus importantes à connaître lors de la migration.

Domaine Rechercher v1 Rechercher 2026-01-01
Conception d’API Points de terminaison à usage multiple (par exemple, Recherche floue utilisée à la fois pour la saisie semi-automatique et la recherche finale) API spécifiques à l’intention (par exemple, Get Geocoding, Get Geocode Autocomplete, Get Reverse Geocoding)
Comportement de saisie semi-automatique Implémenté à l’aide de la recherche floue avec typeahead=true API dédiée Get Geocode Autocomplete
Géocodage final Se reposant souvent sur la correspondance floue pour fournir une « meilleure supposition » Le géocodage hiérarchise l'exactitude et peut ne retourner aucun résultat.
Résultats vides Souvent renvoyé comme correspondance à faible niveau de confiance Peut retourner HTTP 200 avec un tableau de résultats vide quand aucune correspondance n’est trouvée
Gestion du niveau de confiance des résultats La confiance et la qualité de correspondance étaient souvent implicites La confiance, les codes de correspondance et le type d’entité sont explicites et doivent être évalués
Gestion de la hiérarchie d’entités Les résultats flous peuvent retourner des entités faiblement associées Les résultats peuvent être cumulatifs vers une entité de niveau supérieur (par exemple, comté ou région) et doivent être filtrés par type d’entité
Utilisation par lots API Batch disponibles mais souvent facultatives Les API Batch sont recommandées pour les flux de travail à grande échelle et d’enrichissement
Flux de travail d’enrichissement des données Couramment retenté avec une recherche floue Prend explicitement en charge les modèles d’enrichissement avec une indication plus claire en cas d'absence de correspondance.
Structure d’URL Versionné sous les points de terminaison /search/* Points de terminaison spécifiques aux tâches simplifiés (par exemple, /geocode, /reverseGeocode)
Extensibilité future Capacité limitée à faire évoluer les comportements individuels Les API évoluent indépendamment en fonction de l’intention (autocomplétion, géocodage, inverse)

Différences d’utilisation des transactions

Search 2026-01-01 utilise des API spécifiques à l’intention, ce qui peut modifier la manière dont les transactions sont consommées par rapport à Search v1.

Dans la recherche v1, un seul point d'accès à usage multiple a souvent été utilisé pour l'auto-complétion et le géocodage final. Dans La recherche 2026-01-01, ces scénarios sont séparés en API distinctes, ce qui permet d’aligner plus étroitement l’utilisation des transactions avec l’intention de l’utilisateur.

Considérations clés lors de la migration :

  • Utilisez Get Geocode Autocomplete uniquement pour les interactions utilisateur de type anticipé.
  • Utilisez Get Geocoding uniquement lorsqu'une adresse ou un emplacement final est requis.
  • Évitez d’appeler des API de géocodage finales à plusieurs reprises pendant les scénarios de saisie interactifs.
  • Préférez les API de traitement par lots pour les flux de travail de géocodage à grande échelle ou en arrière-plan.

Pour plus d’informations sur la façon dont les transactions Azure Maps sont calculées et facturées, consultez Présentation des transactions Azure Maps.

Modifications de gestion des résultats

La recherche 2026-01-01 met davantage l’accent sur l’exactitude des résultats et la signalisation de correspondance explicite que la recherche v1.

Lors de la migration, passez en revue la façon dont votre application interprète les réponses de recherche :

  • Une demande réussie peut retourner aucun résultat lorsqu’aucune correspondance appropriée n’est trouvée. Pour plus d’informations, consultez Comprendre les résultats de géocodage vides.
  • Les correspondances à faible niveau confiance ou faiblement liées sont moins susceptibles d’être renvoyées automatiquement.
  • Les applications doivent évaluer les valeurs de confiance, les codes de correspondance et les types d’entités lors de la détermination d’un résultat acceptable. Pour plus d’informations, consultez Améliorer la qualité des résultats pour le géocodage basé sur des requêtes.
  • Si une entité demandée est introuvable, le service peut retourner une entité de niveau supérieur dans la hiérarchie d’adresses (par exemple, une région au lieu d’une ville). Pour plus d’informations sur l’évaluation de la qualité des résultats et la validation que les types d’entités retournés correspondent au scénario de recherche prévu, consultez les meilleures pratiques pour transférer le géocodage dans les meilleures pratiques pour le service Recherche Azure Maps.

Ne partez pas du principe que chaque requête réussie retourne un résultat utilisable. L’évaluation explicite des résultats est nécessaire pour maintenir la qualité des données.

Comparaison d’exemples de demande et de réponse

Les exemples suivants montrent comment les requêtes Recherche Azure Maps v1 courantes correspondent à leurs équivalents dans l’API De recherche 2026-01-01. Chaque exemple se concentre sur la même intention utilisateur, mettant en évidence la transition des points d'accès v1 multi-usages aux API conçues pour des intentions spécifiques.

Géocodage direct (adresse → coordonnées)

Dans l’API de recherche v1, le géocodage direct a été couramment effectué à l’aide des points de terminaison Search Address ou Search Fuzzy. Dans Search API 2026-01-01, cette fonctionnalité est fournie par l’API Get Geocoding, qui résout une entrée d’adresse structurée ou non structurée en coordonnées géographiques à l’aide d’un point de terminaison spécifique à l’intention spécifique.

Recherche v1 – Adresse de recherche

GET https://atlas.microsoft.com/search/address/json
  ?api-version=1.0
  &query=1%20Microsoft%20Way%2C%20Redmond%20WA

Recherche 2026-01-01 – Obtenir le géocodage

GET https://atlas.microsoft.com/geocode
  ?api-version=2026-01-01
  &query=1%20Microsoft%20Way%2C%20Redmond%20WA

Recherche approximative d'adresse ou de lieu (résultat final)

L’API Search v1 exposait la résolution floue des adresses et des lieux via un seul point de terminaison Search Fuzzy. Dans l’API De recherche 2026-01-01, ce comportement est remplacé par Get Geocoding, qui gère l’adresse de formulaire libre et place les requêtes tout en séparant les scénarios de saisie semi-automatique et de suggestion en API distinctes.

Rechercher v1 – Recherche floue

GET https://atlas.microsoft.com/search/fuzzy/json
  ?api-version=1.0
  &query=Space%20Needle

Recherche 2026-01-01 – Obtenir le géocodage

GET https://atlas.microsoft.com/geocode
  ?api-version=2026-01-01
  &query=Space%20Needle

Suggestions d’autocomplétion/saisie anticipée

Dans l’API Search v1, le comportement de saisie anticipée était activé en définissant typeahead=true sur le point de terminaison [Search Fuzzy]. Dans l’API de recherche 2026-01-01, les scénarios de saisie semi-automatique sont gérés explicitement par l’API Get Geocode Autocomplete, qui est optimisée pour la saisie utilisateur interactive et les suggestions en temps réel.

Search v1 – Search Fuzzy (utilisation de la saisie anticipée)

GET https://atlas.microsoft.com/search/fuzzy/json
  ?api-version=1.0
  &query=1%20Mic
  &typeahead=true

Search 2026-01-01 – Get Geocode Autocomplete

GET https://atlas.microsoft.com/geocode:autocomplete
  ?api-version=2026-01-01
  &query=1%20Mic
  &coordinates=-122.129,47.639

Pour plus d’informations, consultez Présentation de l’API de saisie semi-automatique d’Azure Maps.

Géocodage par lots

L’API de recherche v1 a pris en charge la résolution d’adresses par lots via le point de terminaison de traitement par lots d’adresses de recherche. Dans l’API de recherche 2026-01-01, cette fonctionnalité est fournie par Get Geocoding Batch, ce qui permet à plusieurs requêtes d’adresse d’être envoyées et traitées dans une requête unique pour les charges de travail à grande échelle ou en arrière-plan.

Recherche v1 – Lot d’adresses de recherche

POST https://atlas.microsoft.com/search/address/batch/json
  ?api-version=1.0

Search 2026-01-01 – Get Geocoding Batch

POST https://atlas.microsoft.com/geocode:batch
  ?api-version=2026-01-01

Géocodage inverse (coordonnées → adresse)

Le géocodage inverse dans l’API de recherche v1 a été effectué à l’aide du point de terminaison inverse de l’adresse de recherche. Dans l'API de recherche 2026-01-01, cette fonctionnalité est disponible via Get Reverse Geocoding, qui convertit les coordonnées de longitude et de latitude en adresse lisible par un humain à l'aide d'une API dédiée à la recherche inverse.

Search v1 – Search Address Reverse

GET https://atlas.microsoft.com/search/address/reverse/json
  ?api-version=1.0
  &position=47.639,-122.129

Recherche 2026-01-01 – Obtenir le géocodage inverse

GET https://atlas.microsoft.com/reverseGeocode
  ?api-version=2026-01-01
  &coordinates=-122.129,47.639

Géocodage inverse par lots

API de recherche v1 permet les recherches inversées par lot via Get Search Address Reverse Batch. Dans l’API de recherche 2026-01-01, ce scénario est pris en charge par Get Reverse Geocoding Batch, ce qui permet de résoudre plusieurs paires de coordonnées en adresses dans une requête unique pour la télémétrie, le suivi ou les pipelines d’enrichissement.

Search v1 – Search Address Reverse Batch

POST https://atlas.microsoft.com/search/address/reverse/batch/json
  ?api-version=1.0

Recherche 2026-01-01 – Récupérer le batch de géocodage inverse

POST https://atlas.microsoft.com/reverseGeocode:batch
  ?api-version=2026-01-01

Récupération des limites administratives

Dans l’API de recherche v1, la géométrie des limites administratives a été récupérée à l’aide d’Obtenir un polygone de recherche. Dans l’API De recherche 2026-01-01, cette fonctionnalité est fournie par l’API Get Polygon , qui retourne la géométrie des limites pour les entités administratives prises en charge, telles que les pays/régions et les villes.

Search v1 – Get Search Polygon

GET https://atlas.microsoft.com/search/polygon/json
  ?api-version=1.0
  &entityId=US-WA

Recherche 2026-01-01 – Obtenir Polygon

GET https://atlas.microsoft.com/polygon
  ?api-version=2026-01-01
  &entityId=US-WA

Liste des éléments à vérifier pour la migration

  • Inventaire de tous les points de terminaison de recherche v1 en cours d’utilisation
  • Identifier l’intention (autocomplétion et géocode final)
  • Remplacez les points de terminaison v1 par des équivalents 2026-01-01
  • Mettre à jour les paramètres de requête
  • Valider l’analyse de réponse
  • Introduire des API de traitement par lots, le cas échéant
  • Mettre à jour la documentation et les exemples

Étapes suivantes

Meilleures pratiques d’utilisation de service Search Azure Maps

  • Dernière mise à jour :