Azure Maps Search 1.0 API の移行

検索 API バージョン 2026-01-01 は 、Search API バージョン 1.0 よりも優先されます。 新しいバージョンでは、タスク固有のエンドポイント、明確な意図、およびスケーラビリティの向上が導入されています。 この記事では、既存の Search v1 統合を移行する方法について説明します。

API 等価性マッピング

主な相違点

Search 2026-01-01 API では、意図固有のエンドポイント、より明確な要求セマンティクス、および Search v1 と比較してより厳密な結果動作が導入されています。 次の表は、移行時に注意すべき最も重要な違いをまとめたものです。

トランザクションの使用状況の違い

Search 2026-01-01 では意図固有の API が使用されます。これは、Search v1 と比較してトランザクションの使用方法を変更できます。

Search v1 では、オートコンプリートと最終的なジオコーディングの両方に、多くの場合、1 つの多目的エンドポイントが使用されていました。 Search 2026-01-01 では、これらのシナリオは個別の API に分割されており、トランザクションの使用をよりユーザーの意図に合わせて調整するのに役立ちます。

移行時の主な考慮事項:

• Get Geocode Autocomplete は、先行入力のユーザー操作にのみ使用します。
• [ ジオコーディングの取得 ] は、最終的な住所または場所が必要な場合にのみ使用します。
• 対話型の入力シナリオでは、最終的なジオコーディング API を繰り返し呼び出さないようにします。
• 大規模またはバックグラウンドのジオコーディング ワークフローには バッチ API を 使用します。

Azure Maps トランザクションの計算方法と課金方法の詳細については、「 Azure Maps トランザクションについて」を参照してください。

結果処理の変更

Search 2026-01-01 では、検索 v1 よりも結果の正確性と明示的な一致シグナルに重点が置かれています。

移行時に、アプリケーションで検索応答がどのように解釈されるかを確認します。

• 適切な一致が見つからない場合、要求が成功しても結果が返 されない 場合があります。 詳細については、空のジオコーディング結果について理解するを参照してください。
• 信頼度の低い一致または緩やかに関連する一致は、自動的に返される可能性が低くなります。
• アプリケーションでは、結果が許容されるかどうかを判断するときに、 信頼度の値、 一致コード、 およびエンティティ型 を評価する必要があります。 詳細については、「 クエリベースのジオコーディングの結果品質の向上」を参照してください。
• 要求されたエンティティが見つからない場合、サービスはアドレス階層内の上位レベルのエンティティ (たとえば、市区町村ではなくリージョン) を返す可能性があります。 結果の品質を評価し、返されたエンティティの種類が意図した検索シナリオと一致することを検証する方法の詳細については、「Azure Maps Search サービスのベスト プラクティス」の順ジオコーディングのベスト プラクティスを参照してください。

成功したすべての要求が使用可能な結果を返すとは考えないでください。 データ品質を維持するには、明示的な結果評価が必要です。

要求と応答の比較例

次の例は、一般的な Azure Maps Search v1 要求が Search API 2026-01-01 で同等の要求にどのようにマップされるかを示しています。 各例では、同じユーザーの意図に焦点を当て、多目的 v1 エンドポイントから意図固有の API への移行を強調しています。

前方ジオコーディング (住所→座標)

Search API v1 では、前方ジオコーディングは通常、検索アドレスまたは検索あいまいエンドポイントを使用して実行されました。 Search API 2026-01-01 では、この機能は Get Geocoding API によって提供されます。この API は、専用の意図固有のエンドポイントを使用して、構造化または非構造化アドレス入力を地理座標に解決します。

検索 v1 - 検索アドレス

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

Search 2026-01-01 – ジオコーディングの取得

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

あいまいアドレスまたは場所の検索 (最終的な結果)

検索 API v1 は、1 つの検索あいまいエンドポイントを介して、あいまいアドレスと場所の解決を提供します。 Search API 2026-01-01 では、この動作は Get Geocoding に置き換えられ、オートコンプリートと提案のシナリオを個別の API に分離しながら、自由形式のアドレスを処理し、クエリを配置します。

検索 v1 – あいまい検索

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

Search 2026-01-01 – ジオコーディングの取得

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

オートコンプリート/先行入力候補

Search API v1 では、[検索あいまい] エンドポイントにtypeahead=trueを設定することで、先行入力動作が有効になりました。 Search API 2026-01-01 では、オートコンプリート シナリオは Get Geocode Autocomplete API によって明示的に処理されます。これは、対話型のユーザー入力とリアルタイムの提案に最適化されています。

検索 v1 – あいまい検索 (先行入力)

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

検索 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

詳細については、「 Azure Maps ジオコード オートコンプリート API の概要」を参照してください。

バッチ フォワード ジオコーディング

Search API v1 では、検索アドレス バッチ エンドポイントを使用したバッチ アドレス解決がサポートされました。 Search API 2026-01-01 では、この機能は Get Geocoding Batch によって提供され、大規模またはバックグラウンドのワークロードに対する 1 つの要求で複数のアドレス クエリを送信および処理できます。

検索 v1 – 検索アドレス バッチ

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

Search 2026-01-01 – ジオコーディング バッチの取得

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

逆ジオコーディング (住所→座標)

Search API v1 での逆ジオコーディングは、検索アドレスの逆引きエンドポイントを使用して実行されました。 Search API 2026-01-01 では、この機能は逆ジオコーディングを使用して使用できます。この機能は、経度と緯度の座標を、専用の逆引き参照 API を使用して人間が判読できるアドレスに変換します。

検索 v1 – 検索アドレスの逆引き

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

Search 2026-01-01 – 逆ジオコーディングを取得する

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

バッチ逆ジオコーディング

Search API v1 では、Get Search Address Reverse Batch を使用したバッチ形式の逆引き参照が有効になっています。 Search API 2026-01-01 では、このシナリオは逆ジオコーディング バッチの取得でサポートされており、テレメトリ、追跡、またはエンリッチメント パイプラインの 1 つの要求で複数の座標ペアをアドレスに解決できます。

検索 v1 – Search Address Reverse Batch

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

Search 2026-01-01 – 逆ジオコーディング バッチを取得する

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

管理境界の取得

Search API v1 では、管理境界ジオメトリは Get Search Polygon を使用して取得されました。 Search API 2026-01-01 では、この機能は、国/地域、都市などのサポートされている管理エンティティの境界ジオメトリを返す Get Polygon API によって提供されます。

検索 v1 – 検索ポリゴンを取得する

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

検索 2026-01-01 – 多角形の取得

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

移行チェックリスト

次のステップ