Azure Maps Search 1.0 API's migreren

Zoek API-versie 2026-01-01 vervangt Search API versie 1.0. De nieuwere versie introduceert taakspecifieke eindpunten, duidelijkere intentie en verbeterde schaalbaarheid. In dit artikel wordt uitgelegd hoe u bestaande Search v1-integraties migreert.

API-equivalentie koppeling

Belangrijke verschillen

De API's search 2026-01-01 introduceren intentiespecifieke eindpunten, duidelijkere semantiek van aanvragen en strenger resultaatgedrag in vergelijking met Search v1. De volgende tabel bevat een overzicht van de belangrijkste verschillen waar u rekening mee moet houden bij het migreren.

Verschillen in gebruik van transacties

Search 2026-01-01 maakt gebruik van intentiespecifieke API's, die kunnen wijzigen hoe transacties worden verbruikt in vergelijking met Search v1.

In Search v1 werd vaak één eindpunt voor meerdere doeleinden gebruikt voor zowel automatisch aanvullen als definitieve geocodering. In Search 2026-01-01 worden deze scenario's gescheiden in afzonderlijke API's, waarmee het transactiegebruik nauwkeuriger wordt afgestemd op de intentie van de gebruiker.

Belangrijke overwegingen bij het migreren:

• Gebruik Get Geocode AutoComplete alleen voor gebruikersinteracties voor het typen.
• Gebruik Get Geocoding alleen wanneer een definitief adres of plaats is vereist.
• Vermijd het aanroepen van uiteindelijke geocoderings-API's herhaaldelijk tijdens interactieve typescenario's.
• Geef de voorkeur aan batch-API's voor grootschalige of geocoderingswerkstromen op de achtergrond.

Zie Inzicht in Azure Maps-transacties voor meer informatie over hoe Azure Maps-transacties worden berekend en gefactureerd.

Wijzigingen in de verwerking van resultaten

Search 2026-01-01 legt meer nadruk op de juistheid van resultaten en expliciete overeenkomstsignalering dan Search v1.

Wanneer u migreert, controleert u hoe uw toepassing zoekantwoorden interpreteert:

• Een geslaagde aanvraag kan geen resultaten retourneren wanneer er geen geschikte overeenkomst wordt gevonden. Zie Inzicht in lege geocoderingsresultaten voor meer informatie.
• Overeenkomsten met laag vertrouwen of die losjes gerelateerd zijn, worden minder waarschijnlijk automatisch teruggestuurd.
• Toepassingen moeten betrouwbaarheidswaarden evalueren, overeenkomen met codes en entiteitstypen bij het bepalen of een resultaat acceptabel is. Zie Resultatenkwaliteit verbeteren voor geocodering op basis van query's voor meer informatie.
• Als een aangevraagde entiteit niet wordt gevonden, kan de service een entiteit op een hoger niveau retourneren in de adreshiërarchie (bijvoorbeeld een regio in plaats van een plaats). Zie Best practices voor het doorsturen van geocodering in best practices voor Azure Maps Search-service voor meer informatie over het evalueren van de kwaliteit van resultaten en het valideren van geretourneerde entiteitstypen die overeenkomen met het beoogde zoekscenario.

Neem niet aan dat elke geslaagde aanvraag een bruikbaar resultaat retourneert. Expliciete evaluatie van resultaten is vereist om de gegevenskwaliteit te behouden.

Vergelijking van verzoek- en antwoordvoorbeelden

In de volgende voorbeelden ziet u hoe veelgebruikte Azure Maps Search v1-aanvragen worden toegewezen aan hun equivalenten in Search API 2026-01-01. Elk voorbeeld richt zich op dezelfde gebruikersintentie en markeert de verschuiving van eindpunten voor meerdere doeleinden v1 tot intentiespecifieke API's.

Voorwaartse geocodering (adres → coördinaten)

In Search API v1 werd geocodering vaak uitgevoerd met behulp van de Search Address- of Search Fuzzy-eindpunten. In Search API 2026-01-01 wordt deze mogelijkheid geboden door de Get Geocoding-API , waarmee gestructureerde of ongestructureerde adresinvoer wordt omgezet in geografische coördinaten met behulp van een toegewezen, intentiespecifiek eindpunt.

Zoeken v1 - Zoekadres

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

Zoeken 2026-01-01 – Geocodering Opzoeken

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

Vage adres- of plaatszoekopdracht (eindresultaat)

Search API v1 heeft een fuzzy adres beschikbaar gesteld en een oplossing voor plaatsen via één Search Fuzzy-eindpunt. In Search API 2026-01-01 wordt dit gedrag vervangen door Geocodering ophalen, waarmee vrije vorm adressen en plaatsvragen worden verwerkt, terwijl autocompletie en scenario’s voor suggesties worden opgesplitst in afzonderlijke API's.

Zoeken v1 - Fuzzy zoeken

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

Zoeken 2026-01-01 – Geocodering Opzoeken

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

Suggesties voor automatisch aanvullen/invoervoorspellingen

In search-API v1 is het type-ahead-gedrag ingeschakeld door het eindpunt [Search Fuzzy] in te stellen typeahead=true . In Search API 2026-01-01 worden automatisch aanvullen-scenario's expliciet verwerkt door de Get Geocode AutoComplete-API , die is geoptimaliseerd voor interactieve gebruikersinvoer en realtime suggesties.

Search v1 – Search Fuzzy (type-ahead gebruik)

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

Zoeken 01‑01‑2026 – Geocode Autocomplete Krijgen

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

Zie Inleiding tot de Azure Maps Geocode AutoComplete-API voor meer informatie.

Geocodering batchgewijs doorsturen

Search API v1 ondersteunde batchadresomzetting via het eindpunt Search Address Batch. In Search API 2026-01-01 wordt deze functionaliteit geboden door Get Geocoding Batch, zodat meerdere adresquery's kunnen worden verzonden en verwerkt in één aanvraag voor grootschalige of achtergrondworkloads.

Search v1 – Zoek Adres Batch

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

Zoeken 2026-01-01 – Geocoderingsbatch ophalen

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

Omgekeerde geocodering (coördinaten → adres)

Reverse geocodering in search-API v1 is uitgevoerd met behulp van het reverse-eindpunt van het zoekadres. In search-API 2026-01-01 is deze mogelijkheid beschikbaar via Reverse Geocodering, waarmee lengte- en breedtegraadcoördinaten worden geconverteerd naar een door mensen leesbaar adres met behulp van een toegewezen REVERSE lookup-API.

Search v1 – Zoek Adres Omgekeerd

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

Zoeken 01-01-2026 – Ontvang Reverse Geocoding

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

Geocodering batchgewijs omkeren

Search API v1 heeft batch reverse lookups ingeschakeld via Get Search Address Reverse Batch. In Search API 2026-01-01 wordt dit scenario ondersteund door Get Reverse Geocoding Batch, zodat meerdere coördinaatparen kunnen worden omgezet naar adressen in één aanvraag voor telemetrie-, tracerings- of verrijkingspijplijnen.

Search v1 - Omgekeerde batch met zoekadressen

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

Zoek 2026-01-01 – Haal Batch met Reverse Geocoding op

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

Ophalen van administratieve grenzen

In search-API v1 is de geometrie van de beheergrens opgehaald met behulp van Get Search Polygon. In Search API 2026-01-01 wordt deze functionaliteit geboden door de Get Polygon-API , die grensgeometrie retourneert voor ondersteunde administratieve entiteiten, zoals landen/regio's en steden.

Search v1 – Zoekgebied ophalen

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

Zoek 2026-01-01 – Verkrijg Veelhoek (Polygon)

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

Migratiecontrolelijst

Volgende stappen