この記事では、Bing Maps Geocode Dataflow API を Azure Maps Geocoding Batch と Reverse Geocoding Batch API に移行する方法について説明します。 Azure Maps Geocoding Batch API は、単一の API 呼び出しで住所または場所の名前の緯度と経度の座標をバッチ モードで取得するために使用されます。 Azure Maps Geocoding Batch API は、クエリのバッチを 1 つの要求で Azure Maps Geocoding API に送信する HTTP POST 要求です。 Azure Maps Reverse Geocoding Batch API は、緯度と経度の座標を人間が理解できる住所に変換するために使用されます。 Azure Maps Reverse Geocoding Batch API は、クエリのバッチを 1 つの要求で Azure Maps Get Reverse Geocoding API に送信する HTTP POST 要求です。
前提条件
- Azure アカウント
- Azure Maps アカウント
- サブスクリプション キー、またはその他の形式の Azure Maps での認証
主な相違点
- Bing Maps Geocode Dataflow API は、同じ API 内で、フォワードおよびリバースのバッチ ジオコーディングをサポートします。 Azure Maps には、フォワード ジオコーディングとリバース ジオコーディング用の API があります。
- Bing Maps Geocode Dataflow API は、場所データを XML またはテキスト (csv、パイプ、タブ区切り) データ ファイルとしてアップロードする必要があります。 Azure Maps Geocoding Batch および Reverse Geocoding Batch API では、データ ファイルのアップロード アプローチではなく、要求の本文に GeoJSON 形式の場所データを含む HTTP POST 要求が使用されます。
- Bing Maps Geocode Dataflow API では、アップロードごとに最大 200,000 個のエンティティがサポートされます。 Azure Maps Geocoding Batch API および Reverse Geocoding Batch API では、同期要求で最大 100 個のバッチ クエリ、および非同期要求で最大 200,000 個のバッチ クエリがサポートされます。
- Bing Maps Geocode Dataflow API で、状態を取得して結果をダウンロードするには、最初のデータ アップロードに続く一連の API 呼び出しが必要です。 Azure Maps Geocoding Batch および Reverse Geocoding Batch API 同期要求では、追加の API 呼び出しは必要ありません。 非同期要求では、バッチ 処理の状態を取得し、結果をダウンロードするために追加の呼び出しが必要です。
- Bing Maps Geocode Dataflow の座標は緯度/経度形式です。 Azure Maps Geocoding Batch および Reverse Geocoding Batch API の座標は、経度/緯度形式です (GeoJSON 形式のため)。
- Azure Maps は、Bing Maps for Enterprise とは異なり、地域スコープの指定をサポートするグローバル サービスです。これにより、データ所在地をヨーロッパ (EU) または米国 (US) の地理的地域 (geo) に制限できます。 (入力データを含む) すべての要求は、指定された地理的領域内でのみ処理されます。 詳しくは、「Azure Maps サービスの地域スコープ」をご覧ください。
セキュリティと認証
Bing Maps for Enterprise がサポートしているのは、API キー認証だけです。 Azure Maps は、サブスクリプション キー、Microsoft Entra ID、Shared Access Signature (SAS) トークンなど、API 呼び出しを認証する方法を複数サポートしています。 Azure Maps のセキュリティと認証の詳細については、Azure Maps Geocoding Batch のドキュメントにある、Azure Maps による認証とセキュリティに関するセクションを参照してください。
要求パラメーター
次の表に、Bing Maps Geocode Dataflow 要求パラメーターと、Azure Maps の同等のパラメーターを示します。
| Bing Maps パラメーター | Azure Maps パラメーター | 説明 |
|---|---|---|
| dataLocation | 不要 | |
| input | 不要 | Bing Maps Geocode Dataflow API では、バッチ ジオコーディング入力データ ファイルの XML 形式とテキスト形式 (csv、タブ、パイプ区切り) がサポートされます。 Azure Maps では、HTTP POST 要求のバッチ ジオコーディング入力データの JSON 形式がサポートされています。 |
| output | 不要 | Bing Maps Geocode Dataflow API では、バッチ ジオコーディング出力データの JSON と XML がサポートされます。 Azure Maps では、バッチ ジオコーディング出力データの JSON 形式がサポートされています。 |
Azure Maps URI パラメーターと要求本文の詳細については、Azure Maps Geocoding Batch と Reverse Geocoding Batch に関するドキュメントをご覧ください。
Bing Maps Data Schema 2.0 と、Azure Maps Geocode Batch および Reverse Geocode Batch API との入力と出力の比較:
| Bing Maps フィールド | Bing Maps 操作 | Azure Maps フィールド | Azure Maps のデータ型 | 説明 |
|---|---|---|---|---|
| Address.AddressLine | ジオコード要求 ジオコード応答 |
addressLine | string | |
| Address.AdminDistrict | ジオコード要求 ジオコード応答 |
adminDistrict | string | |
| Address.CountryRegion | ジオコード要求 ジオコード応答 |
countryRegion | string | |
| Address.District | ジオコード要求 | adminDistrict2 | string | |
| Address.FormattedAddress | ジオコード応答 | |||
| Address.Landmark | ジオコード応答 | サポートされていません | サポートされていません | |
| Address.Locality | ジオコード要求 ジオコード応答 |
locality | string | |
| Address.Neighborhood | ジオコード応答 | neighborhood | string | |
| Address.PostalCode | ジオコード要求 ジオコード応答 |
postalCode | string | |
| Address.PostalTown | ジオコード要求 | adminDistrict3 | ||
| BoundingBox.SouthLatitude, BoundingBox.EastLongitude, BoundingBox.NorthLatitude, BoundingBox.EastLongitude | ジオコード応答 | bbox | number[] | 使用される Azure Maps 投影は EPSG:3857 です。 詳細については、RFC 7946 をご覧ください。 |
| Confidence | ジオコード応答 | confidence | ConfidenceEnum | 詳細については、Azure Maps Geocoding Batch および Reverse Geocoding Batch API のドキュメントをご覧ください。 |
| ConfidenceFilter.MinimumConfidence | ジオコード要求 リバース ジオコード要求 |
サポートされていません | サポートされていません | |
| カルチャ | ジオコード要求 リバース ジオコード要求 |
要求ヘッダー: Accept-Language | string | 詳細については、Azure Maps でサポートされている言語をご覧ください。 |
| EntityType | ジオコード応答 | type | string | 詳細については、Azure Maps Geocoding Batch および Reverse Geocoding Batch API のドキュメントをご覧ください。 |
| FaultReason | ジオコード応答 | サポートされていません | サポートされていません | |
| GeocodeEntity | XML コンテナー | 不要 | 不要 | |
| GeocodeFeed | XML コンテナー | 不要 | 不要 | |
| GeocodePoint | ジオコード応答 | geocodePoints | GeocodePoints[] | 詳細については、Azure Maps Geocoding Batch および Reverse Geocoding Batch API のドキュメントをご覧ください。 |
| GeocodeRequest | XML コンテナー | 不要 | 不要 | Azure Maps には、フォワード ジオコーディングとリバース ジオコーディング用の API があります。 |
| Id | ジオコード要求 | 不要 | 不要 | |
| IncludeEntityTypes | ジオコード要求 リバース ジオコード要求 |
サポートされていません | サポートされていません | |
| IncludeNeighborhood | ジオコード要求 リバース ジオコード要求 |
不要 | 不要 | Azure Maps では、応答で近隣情報が既定で返されます (利用可能な場合)。 |
| IncludeQueryParse | ジオコード要求 | サポートされていません | サポートされていません | |
| Location.Latitude Location.Longitude |
リバース ジオコード要求 | coordinates | number[] | Azure Maps Reverse Geocoding Batch API を使用してリバース ジオコーディングを行う場合は、入力として必要です。 |
| MatchCodes | ジオコード応答 | matchCodes | MatchCodesEnum | 詳細については、Azure Maps Geocoding Batch および Reverse Geocoding Batch API のドキュメントをご覧ください。 |
| MaxResults | ジオコード要求 リバース ジオコード要求 |
top | integer int32 |
Azure Maps では、返される応答の最大数。 既定値は 5、最小値は 1、最大値は 20 です。 |
| 名前 | ジオコード応答 | サポートされていません | サポートされていません | |
| Point.Latitude、Point.Longitude | ジオコード応答 | coordinates | number[] | Bing Maps は、緯度/経度形式で座標を返します。 Azure Maps では、座標が経度/緯度形式で返されます (GeoJSON 形式であるため)。 |
| クエリ | ジオコード要求 | query | string | |
| QueryParseValue | ジオコード応答 | サポートされていません | サポートされていません | |
| ReverseGeocodeRequest | XML コンテナー | 不要 | 不要 | Azure Maps には、フォワード ジオコーディングとリバース ジオコーディング用の API があります。 |
| StatusCode | ジオコード応答 | サポートされていません | サポートされていません | |
| StrictMatch | ジオコード要求 | サポートされていません | サポートされていません | |
| TraceId | ジオコード応答 | サポートされていません | サポートされていません | |
| バージョン | 不要 | 不要 |
Azure Maps Geocoding Batch 応答フィールドの詳細については、応答の定義を参照してください。
要求の例
Bing Maps Geocode Dataflow API 要求:
http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key={BingMapsKey}
Geocode Dataflow のバージョン 2.0 の入力データと出力データのサンプルを示す例については、Geocode Dataflow バージョン 2.0 の入出力データのサンプルに関する記事を参照してください。
Azure Maps Geocoding Batch API 要求:
POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}
ジオコーディング クエリを送信するには、要求の本文に JSON 形式の batchItems 配列が含まれており、Content-Type ヘッダーが application/json に設定されている HTTP POST 要求を使用します。
次の JSON は、2 つのジオコーディング クエリを含むサンプル要求を示しています。1 つの場所は非構造化形式で、1 つの場所は構造化形式です。
{
"batchItems": [
{
"addressLine": "One, Microsoft Way, Redmond, WA 98052",
"top": 2
},
{
"addressLine": "Pike Pl",
"adminDistrict": "WA",
"locality": "Seattle",
"top": 3
}
]
}
Azure Maps Reverse Geocoding Batch API 要求の例:
POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}
リバース ジオコーディング クエリを送信するには、要求の本文に JSON 形式の batchItems 配列が含まれており、Content-Type ヘッダーが application/json に設定されている HTTP POST 要求を使用します。
次の JSON は、2 つのリバース ジオコーディング クエリを含むサンプル要求を示しています。
{
"batchItems": [
{
"coordinates": [
-122.128275,
47.639429
],
"resultTypes": [
"Address",
"PopulatedPlace"
],
"optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
},
{
"coordinates": [
-122.341979399674,
47.6095253501216
],
"optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
}
]
}
応答例
ジオコード ジョブの結果をダウンロードするための URL は、完了というジョブ状態が示すように、Bing Maps Geocode Dataflow バッチ ジョブが正常に処理されたときに提供されます。 Bing Maps Geocode Dataflow の正常な出力の例については、Bing Maps ドキュメントにある、Geocode Dataflow バージョン 2.0 の入出力データのサンプルを参照してください。
次のサンプルは、Azure Maps Geocoding Batch API 要求を実行した場合に HTTP 応答の本文に返される内容を示しています。
{
"summary": {
"successfulRequests": 1,
"totalRequests": 2
},
"batchItems": [
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"address": {
"locality": "Redmond",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King"
}
],
"countryRegion": {
"ISO": "US",
"name": "United States"
},
"postalCode": "98052",
"formattedAddress": "1 Microsoft Way, Redmond, WA 98052",
"addressLine": "1 Microsoft Way"
},
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display",
"Route"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.127028,
47.638545
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.128275,
47.639429
]
},
"bbox": [
-122.1359181505759,
47.63556628242932,
-122.1206318494241,
47.643291717570676
]
}
]
},
{
"error": {
"code": "Conflicting Parameters",
"message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'addressLine' was passed"
}
}
]
}
次のサンプルは、Azure Maps Reverse Geocoding Batch API 要求を実行したときに HTTP 応答の本文に返される内容を示しています。
{
"batchItems": [
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.1294081,
47.6391325
]
},
"properties": {
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.1294081,
47.6391325
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
}
],
"address": {
"addressLine": "15770 NE 31st St",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King Co."
}
],
"countryRegion": {
"name": "United States",
"iso": "US"
},
"locality": "Redmond",
"neighborhood": "Overlake",
"postalCode": "98052",
"formattedAddress": "15770 NE 31st St, Redmond, WA 98052, United States"
},
"confidence": "High",
"matchCodes": [
"Good"
],
"type": "Address"
},
"bbox": [
-122.13705120720665,
47.635269782429326,
-122.12176499279336,
47.64299521757068
]
}
]
},
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.341979399674,
47.6095253501216
]
},
"properties": {
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.341979399674,
47.6095253501216
]
},
"calculationMethod": "Interpolation",
"usageTypes": [
"Display",
"Route"
]
}
],
"address": {
"addressLine": "1736 Pike Pl",
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King Co."
}
],
"countryRegion": {
"name": "United States",
"iso": "US"
},
"intersection": {
"baseStreet": "Pike Pl",
"displayName": "Pike Pl and Stewart St",
"intersectionType": "Near",
"secondaryStreet1": "Stewart St",
"secondaryStreet2": null
},
"locality": "Seattle",
"neighborhood": "Downtown Seattle",
"postalCode": "98101",
"formattedAddress": "1736 Pike Pl, Seattle, WA 98101, United States"
},
"confidence": "Medium",
"matchCodes": [
"Good"
],
"type": "Address"
},
"bbox": [
-122.34961817972945,
47.605662632550924,
-122.33434061961856,
47.61338806769228
]
}
]
}
],
"summary": {
"successfulRequests": 2,
"totalRequests": 2
}
}
トランザクションの使用法
Bing Maps Geocode Dataflow API と同様に、Azure Maps Geocoding Batch および Reverse Geocoding Batch API では、ジオコーディングされたアイテムごとに 1 つの課金対象トランザクションがログに記録されます。 たとえば、バッチ要求でジオコーディングされた 100 の場所では、100 件の課金対象トランザクションが発生します。 Azure Maps トランザクションの詳細については、「Azure Maps トランザクションの理解」を参照してください。
追加情報
その他の Azure Maps Geocoding API
- Get Geocoding: 番地または場所の名前の緯度と経度の座標を取得するために使用します。
- Get Reverse Geocoding: 緯度と経度の座標から所在地住所と位置情報を取得するために使用します。
サポート