Skip to content

Commit dba97cd

Browse files
stevemunkstevemunk
committed
Added a migration guide - 1st draft
1 parent 3041c73 commit dba97cd

1 file changed

Lines changed: 211 additions & 0 deletions

File tree

‎articles/azure-maps/migrate-from-search-version-1.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
---
2+
title: Migrate from Azure Maps Search v1
3+
titleSuffix: Microsoft Azure Maps
4+
description: Learn how to Migrate from Azure Maps Search service version 1 to the latest version.
5+
author: farazgis
6+
ms.author: fsiddiqui
7+
ms.date: 03/28/2026
8+
ms.topic: upgrade-and-migration-article
9+
ms.service: azure-maps
10+
ms.subservice: search
11+
---
12+
13+
# Migrate from Azure Maps Search v1 to Search 2026‑01‑01
14+
15+
[Search][Search v1] API version 1.0 is superseded by the [Search][Search v2026-01-01] 2026‑01‑01 API. The newer version introduces task‑specific endpoints, clearer intent, and improved scalability. This article explains how to migrate existing Search v1 integrations.
16+
17+
> [!IMPORTANT]
18+
> Azure Maps [Search API version 1.0][Search v1] has been superseded by [Search API version 2026‑01‑01][Search v2026-01-01]. While Search v1 continues to function, new development should use the latest Search API to access task‑specific endpoints, improved performance, and long‑term support. To avoid future service disruptions, migrate existing Search v1 integrations to Search 2026‑01‑01.
19+
20+
## API equivalency mapping
21+
22+
| Purpose | Search v1 API | Search 2026‑01‑01 API |
23+
|--------------------|---------------------------------|-------------------------------|
24+
| Forward geocoding | [Get Search Address] | [Get Geocoding] |
25+
| Address/POI search | [Get Search Fuzzy] (final) | [Get Geocoding] |
26+
| Autocomplete | [Get Search Fuzzy] (type‑ahead) | [Get Geocode Autocomplete] |
27+
| Batch geocoding | [Get Search Address Batch] | [Get Geocoding Batch] |
28+
| Reverse geocoding | [Get Search Address Reverse] | [Get Reverse Geocoding] |
29+
| Batch reverse |[Get Search Address Reverse Batch]|[Get Reverse Geocoding Batch] |
30+
| Boundaries | [Get Search Polygon] | [Get Polygon] |
31+
32+
## Request and response example comparison
33+
34+
The following examples show how common Azure Maps Search v1 requests map to their equivalents in Search API 2026‑01‑01. Each example focuses on the same user intent, highlighting the shift from multi‑purpose v1 endpoints to intent‑specific APIs.
35+
36+
### Forward geocoding (address → coordinates)
37+
38+
In [Search API v1][Search v1], forward geocoding was commonly performed using the Search Address or Search Fuzzy endpoints. In [Search API 2026‑01‑01][Search v2026-01-01], this capability is provided by the [Get Geocoding] API, which resolves structured or unstructured address input into geographic coordinates using a dedicated, intent‑specific endpoint.
39+
40+
#### Search v1 – Search Address
41+
42+
```rest
43+
GET https://atlas.microsoft.com/search/address/json
44+
?api-version=1.0
45+
&query=1%20Microsoft%20Way%2C%20Redmond%20WA
46+
```
47+
48+
#### Search 2026‑01‑01 – Get Geocoding
49+
50+
```rest
51+
GET https://atlas.microsoft.com/geocode
52+
?api-version=2026-01-01
53+
&query=1%20Microsoft%20Way%2C%20Redmond%20WA
54+
```
55+
56+
### Fuzzy address or place search (final result)
57+
58+
[Search API v1][Search v1] exposed fuzzy address and place resolution through a single Search Fuzzy endpoint. In [Search API 2026‑01‑01][Search v2026-01-01], this behavior is replaced by [Get Geocoding], which handles free‑form address and place queries while separating autocomplete and suggestion scenarios into distinct APIs.
59+
60+
#### Search v1 – Search Fuzzy
61+
62+
```rest
63+
GET https://atlas.microsoft.com/search/fuzzy/json
64+
?api-version=1.0
65+
&query=Space%20Needle
66+
```
67+
68+
#### Search 2026‑01‑01 – Get Geocoding
69+
70+
```rest
71+
GET https://atlas.microsoft.com/geocode
72+
?api-version=2026-01-01
73+
&query=Space%20Needle
74+
```
75+
76+
### Autocomplete / type‑ahead suggestions
77+
78+
In [Search API v1][Search v1], type‑ahead behavior was enabled by setting `typeahead=true` on the [Search Fuzzy] endpoint. In [Search API 2026‑01‑01][Search v2026-01-01], autocomplete scenarios are handled explicitly by the [Get Geocode Autocomplete] API, which is optimized for interactive user input and real‑time suggestions.
79+
80+
#### Search v1 – Search Fuzzy (type‑ahead usage)
81+
82+
```rest
83+
GET https://atlas.microsoft.com/search/fuzzy/json
84+
?api-version=1.0
85+
&query=1%20Mic
86+
&typeahead=true
87+
```
88+
89+
For a fully functional sample of Fuzzy Search, see [Fuzzy Search with Services Module](https://samples.azuremaps.com/services-module/fuzzy-search-using-services-module).
90+
91+
#### Search 2026‑01‑01 – Get Geocode Autocomplete
92+
93+
```rest
94+
GET https://atlas.microsoft.com/geocode:autocomplete
95+
?api-version=2026-01-01
96+
&query=1%20Mic
97+
&coordinates=-122.129,47.639
98+
```
99+
100+
FOr more information, see [Introducing the Azure Maps Geocode Autocomplete API](https://techcommunity.microsoft.com/blog/azuremapsblog/introducing-the-azure-maps-geocode-autocomplete-api/4455784).
101+
102+
For fully functional samples of autocomplete, see [Autocomplete] (https://samples.azuremaps.com/rest-services/autocomplete) and [Fill Address Form with Autocomplete](https://samples.azuremaps.com/rest-services/fill-address-form-with-autocomplete)
103+
104+
### Batch forward geocoding
105+
106+
[Search API v1][Search v1] supported batch address resolution through the Search Address Batch endpoint. In [Search API 2026‑01‑01][Search v2026-01-01], this functionality is provided by [Get Geocoding Batch], allowing multiple address queries to be submitted and processed in a single request for large‑scale or background workloads.
107+
108+
#### Search v1 – Search Address Batch
109+
110+
```rest
111+
POST https://atlas.microsoft.com/search/address/batch/json
112+
?api-version=1.0
113+
```
114+
115+
#### Search 2026‑01‑01 – Get Geocoding Batch
116+
117+
```rest
118+
POST https://atlas.microsoft.com/geocode:batch
119+
?api-version=2026-01-01
120+
```
121+
122+
### Reverse geocoding (coordinates → address)
123+
124+
Reverse geocoding in [Search API v1][Search v1] was performed using the Search Address Reverse endpoint. In [Search API 2026‑01‑01][Search v2026-01-01], this capability is available through [Get Reverse Geocoding], which converts longitude and latitude coordinates into a human‑readable address using a dedicated reverse‑lookup API.
125+
126+
#### Search v1 – Search Address Reverse
127+
128+
```rest
129+
GET https://atlas.microsoft.com/search/address/reverse/json
130+
?api-version=1.0
131+
&position=47.639,-122.129
132+
```
133+
134+
#### Search 2026‑01‑01 – Get Reverse Geocoding
135+
136+
```rest
137+
GET https://atlas.microsoft.com/reverseGeocode
138+
?api-version=2026-01-01
139+
&coordinates=-122.129,47.639
140+
```
141+
142+
### Batch reverse geocoding
143+
144+
[Search API v1][Search v1] enabled batch reverse lookups through [Get Search Address Reverse Batch]. In [Search API 2026‑01‑01][Search v2026-01-01], this scenario is supported by [Get Reverse Geocoding Batch], allowing multiple coordinate pairs to be resolved to addresses in a single request for telemetry, tracking, or enrichment pipelines.
145+
146+
#### Search v1 – Search Address Reverse Batch
147+
148+
```rest
149+
POST https://atlas.microsoft.com/search/address/reverse/batch/json
150+
?api-version=1.0
151+
```
152+
153+
#### Search 2026‑01‑01 – Get Reverse Geocoding Batch
154+
155+
```rest
156+
POST https://atlas.microsoft.com/reverseGeocode:batch
157+
?api-version=2026-01-01
158+
```
159+
160+
### Administrative boundary retrieval
161+
162+
In [Search API v1][Search v1], administrative boundary geometry was retrieved using [Get Search Polygon]. In [Search API 2026‑01‑01][Search v2026-01-01], this functionality is provided by the [Get Polygon] API, which returns boundary geometry for supported administrative entities such as countries, regions, and cities.
163+
164+
#### Search v1 – Get Search Polygon
165+
166+
```rest
167+
GET https://atlas.microsoft.com/search/polygon/json
168+
?api-version=1.0
169+
&entityId=US-WA
170+
```
171+
172+
#### Search 2026‑01‑01 – Get Polygon
173+
174+
```rest
175+
GET https://atlas.microsoft.com/polygon
176+
?api-version=2026-01-01
177+
&entityId=US-WA
178+
```
179+
180+
## Migration checklist
181+
182+
> [!div class="checklist"]
183+
>
184+
> * Inventory all Search v1 endpoints in use
185+
> * Identify intent (autocomplete vs final geocode)
186+
> * Replace v1 endpoints with 2026‑01‑01 equivalents
187+
> * Update query parameters
188+
> * Validate response parsing
189+
> * Introduce batch APIs where applicable
190+
> * Update documentation and samples
191+
192+
## Next steps
193+
194+
> [!div class="nextstepaction"]
195+
> [Best practices for Azure Maps Search service](how-to-use-best-practices-for-search.md)
196+
197+
[Search v1]: /rest/api/maps/search?view=rest-maps-1.0&preserve-view=true
198+
[Get Search Address]: /rest/api/maps/search/get-search-address
199+
[Get Search Address Batch]: /rest/api/maps/search/get-search-address-batch?view=rest-maps-1.0&tabs=HTTP
200+
[Get Search Address Reverse Batch]: /rest/api/maps/search/get-search-address-reverse-batch?view=rest-maps-1.0&tabs=HTTP
201+
[Get Search Address Reverse]: /rest/api/maps/search/get-search-address-reverse?view=rest-maps-1.0&tabs=HTTP
202+
[Get Search Polygon]: /rest/api/maps/search/get-search-polygon?view=rest-maps-1.0&tabs=HTTP
203+
[Get Search Fuzzy]: /rest/api/maps/search/get-search-fuzzy
204+
205+
[Search v2026-01-01]: /rest/api/maps/search
206+
[Get Geocoding]: /rest/api/maps/search/get-geocoding
207+
[Get Geocode Autocomplete]: /rest/api/maps/search/get-geocode-autocomplete
208+
[Get Geocoding Batch]: /rest/api/maps/search/get-geocoding-batch
209+
[Get Reverse Geocoding]: /rest/api/maps/search/get-reverse-geocoding
210+
[Get Reverse Geocoding Batch]: /rest/api/maps/search/get-reverse-geocoding-batch
211+
[Get Polygon]: /rest/api/maps/search/get-polygon

0 commit comments

Comments
 (0)