Search - Get Reverse Geocoding
Используйте , чтобы получить адрес улицы и сведения о местоположении из координат долготы и широты.
Get Reverse Geocoding
API — это HTTP-запросGET
, используемый для преобразования координаты (например, 37.786505, -122.3862) в понятный человеку адрес. Полезно для отслеживания приложений, в которых вы получаете 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 |
Номер версии API Azure Maps |
coordinates
|
query | True |
number[] |
Координаты расположения, для которого требуется изменить геокод. Пример: &координаты=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 и может быть получен из API учетной записи уровня управления Azure Maps. Инструкции по использованию Azure AD безопасности в Azure Maps см. в следующих статьях. |
|
Accept-Language |
string |
Язык, на котором должны возвращаться результаты поиска. Дополнительные сведения см. в разделе Поддерживаемые языки . |
Ответы
Имя | Тип | Описание |
---|---|---|
200 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 используются для назначения доступа к одной или нескольким учетным записям Azure Maps ресурсов или вложенным ресурсам. Любому пользователю, группе или субъекту-службе можно предоставить доступ через встроенную роль или пользовательскую роль, состоящую из одного или нескольких разрешений на Azure Maps REST API.
Для реализации сценариев рекомендуется ознакомиться с основными понятиями проверки подлинности. Таким образом, это определение безопасности предоставляет решение для моделирования приложений с помощью объектов, способных управлять доступом к определенным API и областям.
Примечание
- Это определение безопасности требует использования заголовка
x-ms-client-id
, чтобы указать, к какому Azure Maps ресурсу приложение запрашивает доступ. Его можно получить из API управления Картами. - Объект
Authorization URL
предназначен для экземпляра общедоступного облака Azure. Национальные облака имеют уникальные URL-адреса авторизации и конфигурации Microsoft Entra ID. - Управление доступом на основе ролей Azure настраивается из плоскости управления Azure с помощью портал Azure, PowerShell, CLI, пакетов SDK для Azure или REST API.
- Использование веб-пакета SDK для Azure Maps позволяет настроить приложение на основе конфигурации для нескольких вариантов использования.
- Дополнительные сведения о платформа удостоверений Майкрософт см. в платформа удостоверений Майкрософт обзоре.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
Имя | Описание |
---|---|
https://atlas.microsoft.com/.default | https://atlas.microsoft.com/.default |
subscription-key
Это общий ключ, который подготавливается при создании ресурса Azure Maps через плоскость управления Azure с помощью портал Azure, PowerShell, CLI, пакетов SDK для Azure или REST API.
С помощью этого ключа любое приложение авторизовано для доступа ко всем REST API. Другими словами, в настоящее время они могут рассматриваться как master ключи к учетной записи, для которой они выданы.
Для общедоступных приложений мы рекомендуем использовать доступ между серверами Azure Maps REST API, где этот ключ можно безопасно хранить.
Type:
apiKey
In:
header
SAS Token
Это маркер подписанного URL-адреса, созданный с помощью операции List SAS для ресурса Azure Maps через плоскость управления Azure с помощью портал Azure, PowerShell, CLI, пакетов SDK для Azure или REST API.
С помощью этого маркера любое приложение авторизовано для доступа с помощью элементов управления доступом на основе ролей Azure и точного контроля срока действия, скорости и регионов, используемых для конкретного маркера. Другими словами, маркер SAS можно использовать, чтобы разрешить приложениям управлять доступом более безопасным способом, чем общий ключ.
Для общедоступных приложений мы рекомендуем настроить определенный список разрешенных источников в ресурсе учетной записи map , чтобы ограничить использование маркера SAS и регулярно обновлять маркер SAS.
Type:
apiKey
In:
header
Примеры
Search point -122.138681, 47.630358
Sample Request
GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates=-122.138681,47.630358
Sample Response
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 |
Название подразделения в стране или регионе для адреса. Этот элемент обычно рассматривается как административное деление первого порядка, но в некоторых случаях он также содержит второе, третье или четвертое подразделение порядка в стране, зависимости или регионе. |
Calculation |
Метод, который использовался для вычисления точки геокода. |
Confidence |
Уровень уверенности в том, что результат геокодированного расположения является совпадением. Используйте это значение с кодом соответствия, чтобы определить более полные сведения о совпадении. Достоверность геокодированного расположения зависит от многих факторов, включая относительную важность геокодированного расположения и расположение пользователя, если указано. |
Country |
|
Error |
Дополнительные сведения об ошибке управления ресурсами. |
Error |
Сведения об ошибке. |
Error |
Сообщение об ошибке |
Feature |
Тип объекта FeatureCollection должен быть FeatureCollection. |
Features |
|
Feature |
Тип компонента должен иметь тип Feature. |
Geocode |
Коллекция точек геокода, которые отличаются способом их вычисления и предлагаемым использованием. |
Geocoding |
Этот объект возвращается из успешного вызова геокодирования. |
Geo |
Допустимый |
Intersection |
Адрес результата. |
Match |
Одно или несколько совпадающих значений кода, представляющих уровень геокодирования для каждого расположения в ответе. Например, геокодированное расположение с кодами Аналогичным образом, геокодированное расположение с кодами Вы можете выбрать
|
Properties | |
Reverse |
Укажите нужные типы сущностей в ответе. Будут возвращены только указанные типы. Если точка не может быть сопоставлена с указанными типами сущностей, сведения о расположении в ответе не возвращаются. Значение по умолчанию — все возможные сущности. Разделенный запятыми список типов сущностей, выбранных из следующих параметров.
Эти типы сущностей упорядочены от наиболее конкретной сущности к наименее определенной сущности. При обнаружении сущностей более одного типа возвращается только наиболее конкретная сущность. Например, если указать Address и AdminDistrict1, так как типы сущностей и сущности были найдены для обоих типов, в ответе будут возвращены только сведения об сущности Address. |
Usage |
Лучше всего использовать точку геокода.
Каждая точка геокода определяется как |
Address
Адрес результата
Имя | Тип | Описание |
---|---|---|
addressLine |
string |
AddressLine, включающая название и номер улицы |
adminDistricts |
Название подразделения в стране или регионе для адреса. Этот элемент обычно рассматривается как административное деление первого порядка, но в некоторых случаях он также содержит второе, третье или четвертое подразделение порядка в стране, зависимости или регионе. |
|
countryRegion | ||
formattedAddress |
string |
Свойство Formatted Address |
intersection |
Адрес результата. |
|
locality |
string |
Свойство locality |
neighborhood |
string |
район собственности |
postalCode |
string |
Почтовый индекс |
AdminDistricts
Название подразделения в стране или регионе для адреса. Этот элемент обычно рассматривается как административное деление первого порядка, но в некоторых случаях он также содержит второе, третье или четвертое подразделение порядка в стране, зависимости или регионе.
Имя | Тип | Описание |
---|---|---|
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
Уровень уверенности в том, что результат геокодированного расположения является совпадением. Используйте это значение с кодом соответствия, чтобы определить более полные сведения о совпадении.
Достоверность геокодированного расположения зависит от многих факторов, включая относительную важность геокодированного расположения и расположение пользователя, если указано.
Имя | Тип | Описание |
---|---|---|
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 |
Идентификатор возвращаемой функции |
properties | ||
type |
Тип компонента должен иметь тип Feature. |
FeatureTypeEnum
Тип компонента должен иметь тип Feature.
Имя | Тип | Описание |
---|---|---|
Feature |
string |
GeocodePoints
Коллекция точек геокода, которые отличаются способом их вычисления и предлагаемым использованием.
Имя | Тип | Описание |
---|---|---|
calculationMethod |
Метод, который использовался для вычисления точки геокода. |
|
geometry |
Допустимый |
|
usageTypes |
Лучше всего использовать точку геокода.
Каждая точка геокода определяется как |
GeocodingResponse
Этот объект возвращается из успешного вызова геокодирования.
Имя | Тип | Описание |
---|---|---|
features | ||
nextLink |
string |
— это ссылка на следующую страницу возвращаемых функций. Если это последняя страница, это поле отсутствует. |
type |
Тип объекта FeatureCollection должен быть FeatureCollection. |
GeoJsonPoint
Допустимый GeoJSON Point
тип геометрии. Дополнительные сведения см. в документе RFC 7946 .
Имя | Тип | Описание |
---|---|---|
bbox |
number[] |
Ограничивающий прямоугольник. Используемая проекция — EPSG:3857. Дополнительные сведения см. в документе RFC 7946 . |
coordinates |
number[] |
— |
type |
string:
Point |
Указывает тип элемента |
Intersection
Адрес результата.
Имя | Тип | Описание |
---|---|---|
baseStreet |
string |
Основная улица для расположения. |
displayName |
string |
Полное имя пересечения. |
intersectionType |
string |
Тип пересечения. |
secondaryStreet1 |
string |
Первая пересекающаяся улица. |
secondaryStreet2 |
string |
Если есть, вторая пересекающаяся улица. |
MatchCodesEnum
Одно или несколько совпадающих значений кода, представляющих уровень геокодирования для каждого расположения в ответе.
Например, геокодированное расположение с кодами Good
соответствия и Ambiguous
означает, что для сведений о расположении было найдено несколько расположений геокода, а служба геокода не имеет иерархии поиска вверх для поиска совпадения.
Аналогичным образом, геокодированное расположение с кодами Ambiguous
соответствия и UpHierarchy
подразумевает, что не удалось найти расположение геокода, совпадающее со всеми предоставленными сведениями о расположении, поэтому службе геокодирования пришлось выполнить поиск в иерархии выше и найти несколько совпадений на этом уровне. Примером результата и UpHierarchy
является предоставление полных сведений Ambiguous
об адресе, но служба геокодирования не может найти совпадение с адресом улицы и вместо этого возвращает сведения для нескольких значений RoadBlock.
Вы можете выбрать
Good
: расположение содержит только одно совпадение, или все возвращенные совпадения считаются сильными. Например, запрос для New York возвращает несколько хороших совпадений.
Ambiguous
: расположение является одним из наборов возможных совпадений. Например, при запросе адреса 128 Main St. ответ может возвращать два расположения для 128 North Main St. и 128 South Main St., так как недостаточно информации, чтобы определить, какой вариант выбрать.
UpHierarchy
: расположение представляет собой перемещение вверх по географической иерархии. Это происходит, когда совпадение для запроса расположения не найдено, поэтому возвращается менее точный результат. Например, если не удается найти совпадение для запрошенного адреса, может быть возвращен код UpHierarchy
соответствия с типом сущности RoadBlock.
Имя | Тип | Описание |
---|---|---|
Ambiguous |
string |
|
Good |
string |
|
UpHierarchy |
string |
Properties
Имя | Тип | Описание |
---|---|---|
address |
Адрес результата |
|
confidence |
Уровень уверенности в том, что результат геокодированного расположения является совпадением. Используйте это значение с кодом соответствия, чтобы определить более полные сведения о совпадении. Достоверность геокодированного расположения зависит от многих факторов, включая относительную важность геокодированного расположения и расположение пользователя, если указано. |
|
geocodePoints |
Коллекция точек геокодирования, которые отличаются способом вычисления и предлагаемым использованием. |
|
matchCodes |
Одно или несколько совпадающих значений кода, представляющих уровень геокодирования для каждого расположения в ответе. Например, геокодированное расположение с кодами Аналогичным образом, геокодированное расположение с кодами Вы можете выбрать
|
|
type |
string |
Одно из двух значений:
|
ReverseGeocodingResultTypeEnum
Укажите нужные типы сущностей в ответе. Будут возвращены только указанные типы. Если точка не может быть сопоставлена с указанными типами сущностей, сведения о расположении в ответе не возвращаются. Значение по умолчанию — все возможные сущности. Разделенный запятыми список типов сущностей, выбранных из следующих параметров.
- Адрес
- Окружение.
- ЗаполнениеPlace
- Почтовый индекс1
- AdminDivision1
- AdminDivision2
- CountryRegion
Эти типы сущностей упорядочены от наиболее конкретной сущности к наименее определенной сущности. При обнаружении сущностей более одного типа возвращается только наиболее конкретная сущность. Например, если указать Address и AdminDistrict1, так как типы сущностей и сущности были найдены для обоих типов, в ответе будут возвращены только сведения об сущности Address.
Имя | Тип | Описание |
---|---|---|
Address |
string |
|
AdminDivision1 |
string |
|
AdminDivision2 |
string |
|
CountryRegion |
string |
|
Neighborhood |
string |
|
PopulatedPlace |
string |
|
Postcode1 |
string |
UsageTypeEnum
Лучше всего использовать точку геокода.
Каждая точка геокода определяется как Route
точка, Display
точка или и то, и другое.
Используйте Route
точки при создании маршрута к расположению. Используйте Display
точки, если отображается расположение на карте. Например, если расположением является парк, Route
точка может указать вход в парк, куда можно въехать на автомобиле, а Display
точка может быть точкой, указывающей центр парка.
Имя | Тип | Описание |
---|---|---|
Display |
string |
|
Route |
string |