Search - Get Reverse Geocoding
経度と緯度の座標から番地と位置情報を取得するには、 を使用します。
Get Reverse Geocoding
API は、座標 (例: 37.786505、-122.3862) を人間が理解できる番地に変換するために使用される HTTP GET
要求です。 デバイスまたは資産から GPS フィードを受信し、座標に関連付けられているアドレスを知りたいアプリケーションを追跡する場合に便利です。 このエンドポイントは、指定された座標のアドレス情報を返します。
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates={coordinates}
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates={coordinates}&resultTypes={resultTypes}&view={view}
URI パラメーター
名前 | / | 必須 | 型 | 説明 |
---|---|---|---|---|
api-version
|
query | True |
string |
Azure Maps API のバージョン番号。 |
coordinates
|
query | True |
number[] |
逆ジオコーディングする場所の座標。 例: &coordinates=lon,lat |
result
|
query |
応答で必要なエンティティの種類を指定します。 指定した型のみが返されます。 指定したエンティティ型にポイントをマップできない場合、応答で位置情報は返されません。 既定値は、考えられるすべてのエンティティです。 次のオプションから選択したエンティティ型のコンマ区切りリスト。
これらのエンティティ型は、最も具体的なエンティティから最も固有でないエンティティに順序付けられます。 複数のエンティティ型のエンティティが見つかった場合は、最も具体的なエンティティのみが返されます。 たとえば、エンティティ型として Address と AdminDistrict1 を指定し、両方の型にエンティティが見つかった場合、応答で返されるのは Address エンティティ情報だけです。 |
||
view
|
query |
string |
ISO 3166-1 Alpha-2 リージョン/国コードを表す文字列。 これにより、指定したユーザー領域に合わせて、地政学的な紛争の境界線とラベルが変更されます。 既定では、View パラメーターは、要求で定義していない場合でも "Auto" に設定されます。 詳細については、「 サポートされているビュー」 を参照し、使用可能なビューを参照してください。 |
要求ヘッダー
名前 | 必須 | 型 | 説明 |
---|---|---|---|
x-ms-client-id |
string |
Azure AD セキュリティ モデルと組み合わせて使用するアカウントを指定します。 これは Azure Maps アカウントの一意の ID を表し、Azure Maps 管理プレーン アカウント API から取得できます。 Azure Maps で Azure AD セキュリティを使用するには、ガイダンスについては、次 の記事を 参照してください。 |
|
Accept-Language |
string |
検索結果を返す言語。 詳細については、「 サポートされている言語 」を参照してください。 |
応答
名前 | 型 | 説明 |
---|---|---|
200 OK |
OK Media Types: "application/geo+json" |
|
Other Status Codes |
予期しないエラーが発生しました。 Media Types: "application/geo+json" |
セキュリティ
AADToken
これらは Microsoft Entra OAuth 2.0 フローです。 Azure ロールベースのアクセス制御と組み合わせて使用すると、Azure Maps REST API へのアクセスを制御できます。 Azure ロールベースのアクセス制御は、1 つ以上の Azure Maps リソース アカウントまたはサブリソースへのアクセスを指定するために使用されます。 ユーザー、グループ、またはサービス プリンシパルには、組み込みのロールまたは Azure Maps REST API への 1 つ以上のアクセス許可で構成されたカスタム ロールを使用してアクセス権を付与できます。
シナリオを実装するには、 認証の概念を表示することをお勧めします。 要約すると、このセキュリティ定義は、特定の API とスコープに対するアクセス制御が可能なオブジェクトを使用してアプリケーションをモデル化するためのソリューションを提供します。
注意
- このセキュリティ定義 では 、 ヘッダーを使用して、
x-ms-client-id
アプリケーションがアクセスを要求している Azure Maps リソースを示す必要があります。 これは、 Maps 管理 API から取得できます。 - は
Authorization URL
、Azure パブリック クラウド インスタンスに固有です。 ソブリン クラウドには、一意の承認 URL と Microsoft Entra ID 構成があります。 - Azure ロールベースのアクセス制御は、Azure portal、PowerShell、CLI、Azure SDK、または REST API を介して Azure 管理プレーン から構成されます。
- Azure Maps Web SDK を使用すると、複数のユース ケースに対してアプリケーションを構成ベースで設定できます。
- Microsoft ID プラットフォームの詳細については、「 Microsoft ID プラットフォームの概要」を参照してください。
型:
oauth2
フロー:
implicit
Authorization URL (承認 URL):
https://login.microsoftonline.com/common/oauth2/authorize
スコープ
名前 | 説明 |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
これは、Azure portal、PowerShell、CLI、Azure SDK、または REST API を使用して Azure 管理プレーンを使用して Azure Maps リソース を作成するときにプロビジョニングされる共有キーです。
このキーを使用すると、すべてのアプリケーションがすべての REST API にアクセスすることが許可されます。 つまり、これらは現在、発行先のアカウントのマスター キーとして扱うことができます。
公開されているアプリケーションの場合、このキーを安全に格納できる Azure Maps REST API のサーバー間アクセスを使用することをお勧めします。
型:
apiKey
/:
header
SAS Token
これは、Azure portal、PowerShell、CLI、Azure SDK、または REST API を介して Azure 管理プレーンを介して、Azure Maps リソース の List SAS 操作から作成される共有アクセス署名トークンです。
このトークンを使用すると、すべてのアプリケーションが Azure ロールベースのアクセス制御を使用してアクセスし、特定のトークンに使用される有効期限、レート、およびリージョンに対するきめ細かい制御が許可されます。 言い換えると、SAS トークンを使用して、アプリケーションが共有キーよりもセキュリティで保護された方法でアクセスを制御できます。
公開されているアプリケーションの場合、 Map アカウント リソース で許可される配信元の特定のリストを構成して、レンダリングの不正使用を制限し、SAS トークンを定期的に更新することをお勧めします。
型:
apiKey
/:
header
例
Search point -122.138681, 47.630358
要求のサンプル
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates=-122.138681,47.630358
応答のサンプル
Content-Type: application/geo+json
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"address": {
"countryRegion": {
"name": "United States"
},
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King County"
}
],
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"locality": "Redmond",
"postalCode": "98052",
"addressLine": "15127 NE 24th St"
},
"type": "Address",
"confidence": "Medium",
"matchCodes": [
"Good"
],
"geocodePoints": [
{
"geometry": {
"type": "Point",
"coordinates": [
-122.138681,
47.630358
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
},
{
"geometry": {
"type": "Point",
"coordinates": [
-122.1386787,
47.6302179
]
},
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
]
},
"geometry": {
"type": "Point",
"coordinates": [
-122.138681,
47.630358
]
},
"bbox": [
-122.14632282407,
47.626495282429325,
-122.13103917593001,
47.63422071757068
]
}
]
}
定義
名前 | 説明 |
---|---|
Address |
結果のアドレス |
Admin |
住所の国または地域のサブ区分名。 この要素は通常、最初の注文管理区分として扱われますが、場合によっては、国、依存関係、またはリージョンの 2 番目、3 番目、または 4 番目の下位区分も含まれます。 |
Calculation |
ジオコーディング ポイントの計算に使用されたメソッド。 |
Confidence |
ジオコーディングされた場所の結果が一致する信頼度。 この値を match コードと共に使用して、一致に関するより完全な情報を確認します。 ジオコーディングされた場所の信頼度は、ジオコーディングされた場所の相対的な重要度やユーザーの場所 (指定されている場合) など、多くの要因に基づいています。 |
Country |
|
Error |
リソース管理エラーの追加情報。 |
Error |
エラーの詳細。 |
Error |
エラー応答 |
Feature |
FeatureCollection オブジェクトの種類は FeatureCollection である必要があります。 |
Features |
|
Feature |
フィーチャーの種類は Feature である必要があります。 |
Geocode |
計算方法と推奨される使用方法が異なるジオコーディング ポイントのコレクション。 |
Geocoding |
このオブジェクトは、ジオコーディング呼び出しが成功した場合に返されます |
Geo |
有効な |
Intersection |
結果のアドレス。 |
Match |
応答内の各場所のジオコーディング レベルを表す 1 つ以上の一致コード値。 たとえば、 と の 同様に、 と の 次の値を指定できます。
|
Properties | |
Reverse |
応答で必要なエンティティの種類を指定します。 指定した型のみが返されます。 指定したエンティティ型にポイントをマップできない場合、応答で位置情報は返されません。 既定値は、考えられるすべてのエンティティです。 次のオプションから選択したエンティティ型のコンマ区切りリスト。
これらのエンティティ型は、最も具体的なエンティティから最も固有でないエンティティに順序付けられます。 複数のエンティティ型のエンティティが見つかった場合は、最も具体的なエンティティのみが返されます。 たとえば、エンティティ型として Address と AdminDistrict1 を指定し、両方の型にエンティティが見つかった場合、応答で返されるのは Address エンティティ情報だけです。 |
Usage |
ジオコーディング ポイントに最適な用途。
各ジオコーディング ポイントは、ポイント、ポイント、 |
Address
結果のアドレス
名前 | 型 | 説明 |
---|---|---|
addressLine |
string |
番地と番号を含む AddressLine |
adminDistricts |
住所の国または地域のサブ区分名。 この要素は通常、最初の注文管理区分として扱われますが、場合によっては、国、依存関係、またはリージョンの 2 番目、3 番目、または 4 番目の下位区分も含まれます。 |
|
countryRegion | ||
formattedAddress |
string |
書式設定された Address プロパティ |
intersection |
結果のアドレス。 |
|
locality |
string |
locality プロパティ |
neighborhood |
string |
neighborhood プロパティ |
postalCode |
string |
郵便番号プロパティ |
AdminDistricts
住所の国または地域のサブ区分名。 この要素は通常、最初の注文管理区分として扱われますが、場合によっては、国、依存関係、またはリージョンの 2 番目、3 番目、または 4 番目の下位区分も含まれます。
名前 | 型 | 説明 |
---|---|---|
name |
string |
対応する adminDistrict フィールドの名前(adminDistrict[0]の場合)、ワシントン、AdminDistrict[1]などの州のフルネームを指定できます。これは郡のフルネームである可能性があります |
shortName |
string |
対応する adminDistrict フィールドの短い名前である adminDistrict[0]の場合、これは WA、AdminDistrict[1]などの状態の短い名前である可能性があります。これは、郡の短い名前である可能性があります |
CalculationMethodEnum
ジオコーディング ポイントの計算に使用されたメソッド。
名前 | 型 | 説明 |
---|---|---|
Interpolation |
string |
ジオコード ポイントは、補間を使用して道路上のポイントと一致しました。 |
InterpolationOffset |
string |
ジオコード ポイントは、道路の側面にポイントをシフトする追加のオフセットを使用して補間を使用して、道路上のポイントと一致しました。 |
Parcel |
string |
ジオコーディング ポイントがパーセルの中心に一致しました。 |
Rooftop |
string |
ジオコード ポイントは、建物の屋上に一致しました。 |
ConfidenceEnum
ジオコーディングされた場所の結果が一致する信頼度。 この値を match コードと共に使用して、一致に関するより完全な情報を確認します。
ジオコーディングされた場所の信頼度は、ジオコーディングされた場所の相対的な重要度やユーザーの場所 (指定されている場合) など、多くの要因に基づいています。
名前 | 型 | 説明 |
---|---|---|
High |
string |
信頼度が に 要求に場所またはビューが含まれている場合、ランク付けは適切に変更される可能性があります。 たとえば、"Paris" の場所クエリでは、"Paris, France" と "Paris, TX" の両方が自信を持って |
Low |
string |
|
Medium |
string |
状況によっては、返される一致が要求で指定された情報と同じレベルになっていない場合があります。 たとえば、要求で住所情報を指定したり、ジオコード サービスが郵便番号と一致することしかできない場合があります。 この場合、ジオコーディング サービスに郵便番号がデータと一致するという信頼度がある場合、信頼度は に クエリ内の位置情報があいまいで、場所をランク付けするための追加情報 (ユーザーの場所や場所の相対的な重要度など) がない場合、信頼度は に クエリ内の位置情報が特定の場所をジオコーディングするのに十分な情報を提供しない場合は、より正確でない場所の値が返され、信頼度が に |
CountryRegion
名前 | 型 | 説明 |
---|---|---|
ISO |
string |
国/地域の ISO |
name |
string |
国/地域の名前 |
ErrorAdditionalInfo
リソース管理エラーの追加情報。
名前 | 型 | 説明 |
---|---|---|
info |
object |
追加情報。 |
type |
string |
追加情報の種類。 |
ErrorDetail
エラーの詳細。
名前 | 型 | 説明 |
---|---|---|
additionalInfo |
エラーの追加情報。 |
|
code |
string |
エラー コード。 |
details |
エラーの詳細です。 |
|
message |
string |
エラー メッセージ。 |
target |
string |
エラーのターゲット。 |
ErrorResponse
エラー応答
名前 | 型 | 説明 |
---|---|---|
error |
error オブジェクト。 |
FeatureCollectionEnum
FeatureCollection オブジェクトの種類は FeatureCollection である必要があります。
名前 | 型 | 説明 |
---|---|---|
FeatureCollection |
string |
FeaturesItem
名前 | 型 | 説明 |
---|---|---|
bbox |
number[] |
境界ボックス。 使用されるプロジェクション - EPSG:3857。 詳細については、 RFC 7946 を参照してください。 |
geometry |
有効な |
|
id |
string |
返される機能の ID |
properties | ||
type |
フィーチャーの種類は Feature である必要があります。 |
FeatureTypeEnum
フィーチャーの種類は Feature である必要があります。
名前 | 型 | 説明 |
---|---|---|
Feature |
string |
GeocodePoints
計算方法と推奨される使用方法が異なるジオコーディング ポイントのコレクション。
名前 | 型 | 説明 |
---|---|---|
calculationMethod |
ジオコーディング ポイントの計算に使用されたメソッド。 |
|
geometry |
有効な |
|
usageTypes |
ジオコーディング ポイントに最適な用途。
各ジオコーディング ポイントは、ポイント、ポイント、 |
GeocodingResponse
このオブジェクトは、ジオコーディング呼び出しが成功した場合に返されます
名前 | 型 | 説明 |
---|---|---|
features | ||
nextLink |
string |
は、返される機能の次のページへのリンクです。 最後のページの場合、このフィールドはありません。 |
type |
FeatureCollection オブジェクトの種類は FeatureCollection である必要があります。 |
GeoJsonPoint
有効な GeoJSON Point
geometry 型。 詳細については、 RFC 7946 を参照してください。
名前 | 型 | 説明 |
---|---|---|
bbox |
number[] |
境界ボックス。 使用されるプロジェクション - EPSG:3857。 詳細については、 RFC 7946 を参照してください。 |
coordinates |
number[] |
は |
type |
string:
Point |
型を指定します |
Intersection
結果のアドレス。
名前 | 型 | 説明 |
---|---|---|
baseStreet |
string |
場所のプライマリ ストリート。 |
displayName |
string |
交差部分の完全な名前。 |
intersectionType |
string |
交差部分の種類。 |
secondaryStreet1 |
string |
最初の交差する通り。 |
secondaryStreet2 |
string |
存在する場合は、2 番目の交差する通り。 |
MatchCodesEnum
応答内の各場所のジオコーディング レベルを表す 1 つ以上の一致コード値。
たとえば、 と のGood
Ambiguous
一致コードを持つジオコーディングされた場所は、位置情報に対して複数のジオコーディングの場所が見つかり、ジオコーディング サービスで一致を検索するための階層が検索されていないことを意味します。
同様に、 と のAmbiguous
UpHierarchy
一致コードを持つジオコーディングされた場所は、指定されたすべての位置情報と一致するジオコーディングの場所が見つからなかったことを意味するため、ジオコーディング サービスは階層を上から検索し、そのレベルで複数の一致を検出する必要がありました。 と の結果のAmbiguous
UpHierarchy
例は、完全な住所情報を指定したが、ジオコード サービスが番地の一致を見つけられないため、代わりに複数の RoadBlock 値の情報を返す場合です。
次の値を指定できます。
Good
: 場所に一致するものが 1 つだけあるか、返されたすべての一致が厳密な一致と見なされます。 たとえば、New York のクエリでは、いくつかの Good 一致が返されます。
Ambiguous
: 場所は、一致する可能性のある一連の 1 つです。 たとえば、番地 128 Main St.を照会すると、選択するオプションを決定するのに十分な情報がないため、応答から 128 North Main St. と 128 South Main St. の 2 つの場所が返されることがあります。
UpHierarchy
: 場所は、地理的階層の上への移動を表します。 これは、場所要求の一致が見つからなかった場合に発生するため、より正確でない結果が返されます。 たとえば、要求されたアドレスの一致が見つからない場合、RoadBlock エンティティ型を持つ の UpHierarchy
一致コードが返される場合があります。
名前 | 型 | 説明 |
---|---|---|
Ambiguous |
string |
|
Good |
string |
|
UpHierarchy |
string |
Properties
名前 | 型 | 説明 |
---|---|---|
address |
結果のアドレス |
|
confidence |
ジオコーディングされた場所の結果が一致する信頼度。 この値を match コードと共に使用して、一致に関するより完全な情報を確認します。 ジオコーディングされた場所の信頼度は、ジオコーディングされた場所の相対的な重要度やユーザーの場所 (指定されている場合) など、多くの要因に基づいています。 |
|
geocodePoints |
計算方法と推奨される使用方法が異なるジオコーディング ポイントのコレクション。 |
|
matchCodes |
応答内の各場所のジオコーディング レベルを表す 1 つ以上の一致コード値。 たとえば、 と の 同様に、 と の 次の値を指定できます。
|
|
type |
string |
つぎのいずれかです。
|
ReverseGeocodingResultTypeEnum
応答で必要なエンティティの種類を指定します。 指定した型のみが返されます。 指定したエンティティ型にポイントをマップできない場合、応答で位置情報は返されません。 既定値は、考えられるすべてのエンティティです。 次のオプションから選択したエンティティ型のコンマ区切りリスト。
- Address
- "近隣"
- PopulatedPlace
- Postcode1
- AdminDivision1
- AdminDivision2
- CountryRegion
これらのエンティティ型は、最も具体的なエンティティから最も固有でないエンティティに順序付けられます。 複数のエンティティ型のエンティティが見つかった場合は、最も具体的なエンティティのみが返されます。 たとえば、エンティティ型として Address と AdminDistrict1 を指定し、両方の型にエンティティが見つかった場合、応答で返されるのは Address エンティティ情報だけです。
名前 | 型 | 説明 |
---|---|---|
Address |
string |
|
AdminDivision1 |
string |
|
AdminDivision2 |
string |
|
CountryRegion |
string |
|
Neighborhood |
string |
|
PopulatedPlace |
string |
|
Postcode1 |
string |
UsageTypeEnum
ジオコーディング ポイントに最適な用途。
各ジオコーディング ポイントは、ポイント、ポイント、Display
またはその両方としてRoute
定義されます。
場所へのルートを作成する場合は、ポイントを使用 Route
します。 マップ上に位置を表示する場合は、ポイントを使用 Display
します。 たとえば、場所が公園の場合、 Route
ポイントは車で入力できる公園への入り口を指定し Display
、ポイントは公園の中心を指定するポイントである場合があります。
名前 | 型 | 説明 |
---|---|---|
Display |
string |
|
Route |
string |