Azure Maps Search Service を使用して場所を検索する
Search Service は、開発者が住所、場所、名前またはカテゴリ別の事業の一覧、およびその他の地理情報を検索できるように設計された RESTful API のセットです。 サービスでは、従来のジオコーディングをサポートするだけでなく、緯度と経度に基づいて住所や交差道路の逆ジオコーディングを行うこともできます。 検索で返された緯度と経度の値は、Route や Weather などの他の Azure Maps サービスでパラメーターとして使用できます。
この記事では、次の方法を示します。
- Search Address を使用して、住所 (ジオコード アドレスの場所) の緯度と経度の座標を要求する。
- Fuzzy Search を使用して、住所または目的地 (POI) を検索する。
- Reverse Address Search を使用して、座標位置を番地に変換する。
- Search Address Reverse Cross Street を使用して、座標位置を人が理解できる交差点に変換します。これは、デバイスまたは資産から GPS フィードを受信し、座標の位置を知りたい追跡アプリケーションで最もよく必要とされます。
前提条件
このチュートリアルでは Postman アプリケーションを使用していますが、別の API 開発環境を選択することもできます。
住所の緯度と経度を要求する (ジオコーディング)
このセクションの例では、Get Search Address を使用して、住所を緯度および経度の座標に変換します。 このプロセスはジオコーディングとも呼ばれています。 応答では、座標が返されるだけでなく、番地、郵便番号、地方自治体、国または地域の情報などの詳細な住所プロパティも返されます。
ヒント
ジオコーディングする一連の住所がある場合は、Post Search Address Batch を使用して、クエリのバッチを単一の要求で送信できます。
Postman アプリで、 [New](新規) を選択して要求を作成します。 [新規作成] ウィンドウで [HTTP 要求] を選択します。 要求の [要求名] を入力します。
ビルダー タブで GET HTTP メソッドを選択し、次の URL を入力します。 この要求では、特定の住所 (
400 Braod St, Seattle, WA 98109) を検索します。 この要求と、この記事で触れられているその他の要求では、{Your-Azure-Maps-Subscription-key}をAzure Maps サブスクリプション キーに置き換えます。https://atlas.microsoft.com/search/address/json?&subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&language=en-US&query=400 Broad St, Seattle, WA 98109青い [送信] ボタンを選択します。 応答本文には、1 つの場所のデータが含まれます。
次に、場所の候補が複数個ある住所を検索します。 [パラメーター] セクションで、
queryキーを400 Broad, Seattleに変更します。 青い [送信] ボタンを選択します。
次に、
queryキーを400 Broaに設定してみます。[送信] ボタンを選択します。 応答には、複数の国/地域からの結果が含まれます。 ユーザーの関連領域に結果をジオバイアスするには、常にできるだけ多くの場所の詳細を要求に追加してください。
あいまい検索
Fuzzy Search では、標準的な単一行の自由形式検索がサポートされています。 検索要求に対するユーザー入力の種類がわからない場合は、Azure Maps Search Fuzzy API を使用することをお勧めします。 クエリには、完全なアドレスまたはアドレスの一部を入力できます。 また、目的地 (POI) の名前、POI カテゴリ、ブランドの名前などの POI トークンを入力することもできます。 さらに、検索結果の関連性を高めるため、座標位置と半径を使用するか、境界ボックスを定義して、クエリ結果を制限します。
ヒント
ほとんどの検索クエリでは、パフォーマンスを向上させて想定外の結果を減らすために、既定で maxFuzzyLevel=1 に設定されます。 あいまいさのレベルを調整するには、maxFuzzyLevel または minFuzzyLevel パラメーターを使用します。 maxFuzzyLevel の詳細と省略可能なパラメーターの全一覧については、Fuzzy Search URI パラメーターに関するページを参照してください。
あいまい検索を使用した住所の検索
このセクションの例では、Fuzzy Search を使用して世界中で pizza を検索し、次に特定の国/地域を対象に検索します。 最後に、座標位置と半径を使用して検索の範囲を特定の領域に設定し、返される結果の数を制限する方法について説明します。
重要
ユーザーの関連領域に結果をジオバイアスするには、常にできるだけ多くの場所の詳細を追加してください。 詳しくは、「検索のベスト プラクティス」をご覧ください。
Postman アプリで、 [New](新規) を選択して要求を作成します。 [新規作成] ウィンドウで [HTTP 要求] を選択します。 要求の [要求名] を入力します。
ビルダー タブで GET HTTP メソッドを選択し、次の URL を入力します。 この要求と、この記事で触れられているその他の要求では、
{Your-Azure-Maps-Subscription-key}を実際の Azure Maps サブスクリプション キーに置き換えます。https://atlas.microsoft.com/search/fuzzy/json?&api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=pizzaNote
URL パスの json 属性で、応答形式が決定まります。 この記事では、使いやすく、読みやすい json を使用します。 サポートされている他の応答形式については、URI パラメーターのリファレンスに関するドキュメントの
formatパラメーターの定義を参照してください。[送信] を選択し、応答の本体を確認します。
あいまいなクエリ文字列 "pizza" からは結果として、"pizza" と "restaurant" のカテゴリに含まれる 10 か所の目的地 (POI) が返されました。 各結果には、該当の場所の番地、緯度値と経度値、ビュー ポート、エントリ ポイントなどの詳細が含まれています。 このクエリでは結果が雑多で、特定の参照場所には関連付けられません。
次の手順では、
countrySetパラメーターを使用して、アプリケーションの対象にする必要がある国または地域のみを指定します。 サポートされている国または地域の完全な一覧については、検索範囲に関するセクションをご覧ください。既定の動作では全世界が検索されるので、必要のない結果が返される可能性があります。 次に、米国のみで pizza を検索します。 [パラメーター] セクションに
countrySetキーを追加し、その値をUSに設定します。countrySetキーをUSに設定すると、結果が米国に制限されます。
これで、結果が国コードによってバインドされ、クエリでは米国のピザ レストランが返されます。
さらに絞り込んだ検索結果を取得するには、緯度と経度の座標ペアを範囲として検索できます。 次の例では、シアトル スペース ニードルの緯度と経度の座標を使用します。 半径 400 m 以内の結果のみを取得したいので、
radiusパラメーターを追加します。 また、limitパラメーターを追加して、最寄りの 5 つのピザ屋に結果を制限します。[パラメーター] セクションに次のキー/値のペアを追加します。
キー 値 lat 47.620525 lon -122.349274 radius 400 limit 5 [Send] を選択します。 応答には、シアトル スペース ニードルの近くにあるピザ レストランの結果が含まれています。
住所の逆引き検索を使用した所在地住所の検索
Get Search Address Reverse は、座標を人間が理解できる番地に変換します。 この API は、GPS フィードを利用して特定の座標点の住所を検出する必要があるアプリケーションでよく使用されます。
重要
ユーザーの関連領域に結果をジオバイアスするには、常にできるだけ多くの場所の詳細を追加してください。 詳しくは、「検索のベスト プラクティス」をご覧ください。
ヒント
リバース ジオコーディングする一連の座標位置がある場合は、Post Search Address Reverse Batch を使用して、クエリのバッチを単一の要求で送信できます。
この例では、利用可能ないくつかのオプション パラメーターを使用して、逆方向の検索を行う方法を示します。 省略可能なパラメーターの完全な一覧については、逆方向の検索のパラメーターに関するセクションをご覧ください。
Postman アプリで、 [New](新規) を選択して要求を作成します。 [新規作成] ウィンドウで [HTTP 要求] を選択します。 要求の [要求名] を入力します。
ビルダー タブで GET HTTP メソッドを選択し、次の URL を入力します。 この要求と、この記事で触れられているその他の要求では、
{Your-Azure-Maps-Subscription-key}を実際の Azure Maps サブスクリプション キーに置き換えます。 要求は次の URL のようになります。https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=47.591180,-122.332700&number=1[送信] を選択し、応答の本体を確認します。 1 つのクエリ結果が表示されます。 応答には、セーフコ フィールドのキー アドレス情報が含まれます。
次に、[パラメーター] セクションに次のキー/値のペアを追加します。
キー 値 戻り値 number 1 通りの側 (左/右) とその数値からのオフセット位置を応答に含めることができます。 returnSpeedLimit true その住所での制限速度が返されます。 returnRoadUse true その住所での道路用途の種類が返されます。 使用できるすべての道路用途の種類については、道路用途の種類に関するセクションをご覧ください。 returnMatchType true 一致の種類を返します。 使用できるすべての値については、Reverse Address Search の結果に関するページを参照してください。 
[送信] を選択し、応答の本体を確認します。
次に、
entityTypeキーを追加し、その値をMunicipalityに設定します。entityTypeキーを使用すると、前の手順のreturnMatchTypeキーがオーバーライドされます。 地方自治体に関する情報を要求しているので、returnSpeedLimitとreturnRoadUseも削除する必要があります。 使用できるすべてのエンティティ型については、エンティティ型に関するセクションをご覧ください。
[Send] を選択します。 この結果を手順 5 で返された結果と比較します。 要求されたエンティティ型が
municipalityであるため、応答に番地の情報は含まれていません。 また、返されたgeometryIdは、Azure Maps Get Search Polygon API で境界多角形を要求するときに使用できます。
ヒント
これらのパラメーターと他のパラメーターの詳細については、Reverse Search のパラメーターに関するページを参照してください。
交差点住所の逆引き検索を使用して交差点を検索する
この例では、住所の座標に基づいて交差道路を検索する方法を示します。
Postman アプリで、 [New](新規) を選択して要求を作成します。 [新規作成] ウィンドウで [HTTP 要求] を選択します。 要求の [要求名] を入力します。
ビルダー タブで GET HTTP メソッドを選択し、次の URL を入力します。 この要求と、この記事で触れられているその他の要求では、
{Your-Azure-Maps-Subscription-key}を実際の Azure Maps サブスクリプション キーに置き換えます。 要求は次の URL のようになります。https://atlas.microsoft.com/search/address/reverse/crossstreet/json?&api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&language=en-US&query=47.591180,-122.332700
[送信] を選択し、応答の本体を確認します。 応答に
South Atlantic StreetというcrossStreetの値が含まれていることがわかります。