Search - Get Search Address Reverse

Ссылка

Служба:: Maps

Версия API:: 1.0

Используется для получения сведений об адресе и местоположении из координат широты и долготы.
API Get Search Address Reverse — это HTTP-запрос GET , который возвращает адрес или расположение при заданных координатах широты и долготы.

Иногда может потребоваться перевести координату (например, 37,786505, -122,3862) в понятный человеку адрес. Чаще всего это необходимо в приложениях отслеживания, где вы получаете gps-канал от устройства или ресурса и хотите знать, по какому адресу расположена координата. Эта конечная точка возвращает сведения об адресе для заданной координаты.

GET https://atlas.microsoft.com/search/address/reverse/{format}?api-version=1.0&query={query}

С использованием необязательных параметров:

GET https://atlas.microsoft.com/search/address/reverse/{format}?api-version=1.0&query={query}&language={language}&returnSpeedLimit={returnSpeedLimit}&heading={heading}&radius={radius}&number={number}&returnRoadUse={returnRoadUse}&roadUse={roadUse}&allowFreeformNewline={allowFreeformNewline}&returnMatchType={returnMatchType}&entityType={entityType}&view={view}

Параметры URI

Имя	В	Обязательно	Тип	Описание
format	path	True	ResponseFormat	Требуемый формат ответа. Значение может быть либо json , либо xml.
api-version	query	True	string	Номер версии API Azure Maps
query	query	True	number[]	Применимый запрос, указанный в виде строки, разделенной запятыми, состоящей из широты и долготы, например "47,641268,-122.125679".
allowFreeformNewline	query		boolean	Формат новых строк в отформатируемом адресе. Если задано значение true, адрес будет содержать новые строки. Если значение равно false, новые линии будут преобразованы в запятые.
entityType	query		GeographicEntityType	Указывает уровень фильтрации, выполняемой по географическим регионам. Сужает поиск указанных типов сущностей geography, например возвращает только муниципалитет. Полученный ответ будет содержать идентификатор geography, а также совпадающий тип сущности. Если указать несколько сущностей в виде списка, разделенного запятыми, конечная точка вернет наименьшую доступную сущность. Возвращаемый идентификатор геометрии можно использовать для получения геометрии этой географической области с помощью API получения Поиск многоугольников. Следующие параметры игнорируются при установке entityType: heading number returnRoadUse returnSpeedLimit roadUse returnMatchType
heading	query		integer	Направление направления транспортного средства в градусах, для перемещения по сегменту дорожного движения. 0 — север, 90 — восток и т. д. Значения варьируются от –360 до 360. Точность может включать до одного десятичного разряда
language	query		string	Язык, на котором должны возвращаться результаты поиска. Должен быть одним из поддерживаемых языковых тегов IETF без учета регистра. Если данные на указанном языке недоступны для определенного поля, используется язык по умолчанию. Дополнительные сведения см. в разделе Поддерживаемые языки .
number	query		string	Номер улицы в виде строки. Если число отправляется вместе с запросом, ответ может включать в себя сторону улицы (слева или справа), а также позицию смещения для этого числа.
radius	query		integer	Радиус в метрах до для ограничения результатов определенной областью
returnMatchType	query		boolean	Включите сведения о типе соответствия геокодера, достигнутого в ответе.
returnRoadUse	query		boolean	Логическое. Включение возврата массива использования дорог для обратных геокодов на уровне улицы
returnSpeedLimit	query		boolean	Логическое. Включение возврата размещенного ограничения скорости
roadUse	query		RoadUseType[]	Чтобы ограничить обратные геокоды определенным типом дорожного использования. Массив использования дорог для обратных геокодов может быть одним или несколькими из LimitedAccess, Артериальный, Терминал, Рампа, Ротарий, LocalStreet
view	query		LocalizedMapView	Параметр View (также называемый параметром "регион пользователя") позволяет отображать правильные карты для определенной страны или региона для геополитически спорных регионов. Разные страны или регионы имеют разные представления таких регионов, и параметр View позволяет приложению соответствовать представлению, требуемому для страны или региона, который будет обслуживать приложение. По умолчанию параметр View имеет значение Unified, даже если он не определен в запросе. Вы несете ответственность за определение расположения пользователей, а затем правильное определение параметра View для этого расположения. Кроме того, можно задать параметр View=Auto, который будет возвращать данные карты на основе IP-адреса запроса. Параметр View в Azure Maps должен использоваться в соответствии с применимыми законами, включая те, которые касаются сопоставления, страны или региона, в которых доступны карты, изображения и другие данные, а также содержимое третьих лиц, доступ к которому вы имеете через Azure Maps. Пример: view=IN. Дополнительные сведения и доступные представления см. в разделе Поддерживаемые представления .

Заголовок запроса

Имя	Обязательно	Тип	Описание
x-ms-client-id		string	Указывает, какая учетная запись предназначена для использования в сочетании с моделью безопасности Microsoft Entra ID. Он представляет уникальный идентификатор учетной записи Azure Maps и может быть получен из API учетной записи уровня управления Azure Maps. Инструкции по использованию Microsoft Entra ID безопасности в Azure Maps см. в следующих статьях.

Ответы

Имя	Тип	Описание
200 OK	ReverseSearchAddressResult	ОК
Other Status Codes	ErrorResponse	Произошла непредвиденная ошибка.

Безопасность

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 позволяет настроить приложение на основе конфигурации для нескольких вариантов использования.
Дополнительные сведения о платформа удостоверений Майкрософт см. в платформа удостоверений Майкрософт обзоре.

Тип: oauth2
Flow: implicit
URL-адрес авторизации: https://login.microsoftonline.com/common/oauth2/authorize

Области

Имя	Описание
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Это общий ключ, который подготавливается при создании учетной записи Azure Maps в портал Azure или с помощью PowerShell, CLI, пакетов AZURE SDK или REST API.

С помощью этого ключа любое приложение может получить доступ ко всем REST API. Другими словами, этот ключ можно использовать в качестве ключа master в учетной записи, в которую они выдаются.

Для общедоступных приложений мы рекомендуем использовать подход конфиденциальных клиентских приложений для доступа к Azure Maps REST API, чтобы обеспечить безопасное хранение ключа.

Тип: apiKey
В: query

SAS Token

Это маркер подписанного URL-адреса, созданный с помощью операции List SAS для ресурса Azure Maps через плоскость управления Azure с помощью портал Azure, PowerShell, CLI, пакетов SDK для Azure или REST API.

С помощью этого маркера любое приложение авторизовано для доступа с помощью элементов управления доступом на основе ролей Azure и точного контроля срока действия, скорости и регионов, используемых для конкретного маркера. Другими словами, маркер SAS можно использовать, чтобы разрешить приложениям управлять доступом более безопасным способом, чем общий ключ.

Для общедоступных приложений мы рекомендуем настроить определенный список разрешенных источников в ресурсе учетной записи map , чтобы ограничить использование маркера SAS и регулярно обновлять маркер SAS.

Тип: apiKey
В: header

Примеры

Searches addresses for coordinates 37.337,-121.89

Образец запроса

HTTP

GET https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&query=37.337,-121.89

Пример ответа

Код состояния:: 200

{
  "summary": {
    "queryTime": 5,
    "numResults": 1
  },
  "addresses": [
    {
      "address": {
        "streetNumber": "31",
        "routeNumbers": [],
        "streetName": "N 2nd St",
        "streetNameAndNumber": "31 N 2nd St",
        "countryCode": "US",
        "countrySubdivisionCode": "CA",
        "countrySubdivisionName": "California",
        "municipality": "San Jose",
        "postalCode": "95113",
        "country": "United States of America",
        "countryCodeISO3": "USA",
        "freeformAddress": "31 N 2nd St, San Jose CA 95113",
        "extendedPostalCode": "951131217"
      },
      "position": "37.337090,-121.889820"
    }
  ]
}

Определения

Имя	Описание
Address	Адрес результата
BoundingBoxCompassNotation	Ограничивающий прямоугольник расположения.
Entity	Источник типа сущности ограничивающего прямоугольника. Для обратного геокодирования это всегда равно положению.
ErrorAdditionalInfo	Дополнительные сведения об ошибке управления ресурсами.
ErrorDetail	Сведения об ошибке.
ErrorResponse	Сообщение об ошибке
GeographicEntityType	Тип сущности Geography. Отображается только в том случае, если entityType был запрошен и доступен.
LatLongPairAbbreviated	Расположение, представленное в виде широты и долготы с использованием коротких имен "lat" & "lon".
LocalizedMapView	Параметр View (также называемый параметром "регион пользователя") позволяет отображать правильные карты для определенной страны или региона для геополитически спорных регионов. Разные страны или регионы имеют разные представления таких регионов, и параметр View позволяет приложению соответствовать представлению, требуемому для страны или региона, который будет обслуживать приложение. По умолчанию параметр View имеет значение Unified, даже если он не определен в запросе. Вы несете ответственность за определение расположения пользователей, а затем правильное указание параметра View для этого расположения. Кроме того, можно задать параметр View=Auto, который будет возвращать данные карты на основе IP-адреса запроса. Параметр View в Azure Maps должен использоваться в соответствии с применимыми законами, включая те, которые касаются сопоставления, страны или региона, в которой доступны карты, изображения и другие данные и содержимое третьих лиц, доступ к которому вы имеете через Azure Maps. Пример: view=IN. Дополнительные сведения и доступные представления см. в разделе Поддерживаемые представления.
MatchType	Типы совпадений для операции обратного поиска адресов.
QueryType	Тип возвращаемого запроса: NEARBY или NON_NEAR.
ResponseFormat	Требуемый формат ответа. Значение может быть либо json , либо xml.
ReverseSearchAddressResult	Этот объект возвращается из успешного обратного вызова Поиск Address
ReverseSearchAddressResultItem	Объект result для обратного ответа Поиск Address
RoadUseType	Описывает возможные способы использования дороги.
SearchSummary	Объект Summary для ответа API Поиск.

Address

Адрес результата

Имя	Тип	Описание
boundingBox	BoundingBoxCompassNotation	Ограничивающий прямоугольник расположения.
buildingNumber	string	Номер здания на улице. Не рекомендуется, вместо этого используйте streetNumber.
country	string	название страны или региона
countryCode	string	Страна (примечание. Это двухбуквенный код, а не название страны или региона.)
countryCodeISO3	string	Код страны ISO alpha-3
countrySecondarySubdivision	string	Округ
countrySubdivision	string	Область, республика, край
countrySubdivisionCode	string	`countrySubdivisionCode` с префиксом `countryCode` ( countryCode-countrySubdivisionCode ), а дефис формирует код ISO 3166-2. Примеры: TX для Техаса, SCT для Шотландии и ON для Онтарио.
countrySubdivisionName	string	Полное имя первого уровня административной иерархии страны или региона. Это поле отображается только в том случае, если countrySubdivision представлено в сокращенной форме. Поддерживается только для США, Канады и Соединенного Королевства.
countryTertiarySubdivision	string	Именованной области
crossStreet	string	Название пересекаемой улицы.
extendedPostalCode	string	Расширенный почтовый индекс (доступность зависит от региона).
freeformAddress	string	Адресная строка, отформатированная в соответствии с правилами форматирования страны или региона источника результата или в случае страны или региона, его полного названия страны или региона.
localName	string	Компонент адреса, представляющий имя географической области или местности, которая группирует несколько адресуемых объектов для целей адресации, не являясь административной единицей. Это поле используется для сборки `freeformAddress` свойства . `localName` представляет почтовый муниципалитет. В зависимости от расположения — `localName` это общеизвестное название города или города. Для общеизвестного названия города или города используйте `localName` вместо `municipality`.
municipality	string	Город или город Примечание. `municipality` Представляет жилой муниципалитет. В зависимости от расположения `municipality` значение может отличаться от общего имени города или города. Для общего имени города или города рекомендуется `localName` использовать значение вместо `municipality` значения.
municipalitySubdivision	string	Sub / Super City
neighbourhood	string	Район — это географически локализованная территория в пределах города или города с отличительными характеристиками и социальными взаимодействиями между жителями.
postalCode	string	Почтовый индекс / почтовый индекс
routeNumbers	string[]	Коды, используемые для однозначной идентификации улицы
street	string	Название улицы. Не рекомендуется, вместо этого используйте streetName.
streetName	string	Название улицы.
streetNameAndNumber	string	Название и номер улицы.
streetNumber	string	Номер здания на улице.

BoundingBoxCompassNotation

Ограничивающий прямоугольник расположения.

Имя	Тип	Описание
entity	Entity	Источник типа сущности ограничивающего прямоугольника. Для обратного геокодирования это всегда равно положению.
northEast	string	Северо-восточная широта,долгота координаты ограничивающего прямоугольника в виде поплавков с раздели-запятыми
southWest	string	Широта юго-запада, координата долготы ограничивающего прямоугольника в виде поплавков с разделимы-запятыми

Entity

Источник типа сущности ограничивающего прямоугольника. Для обратного геокодирования это всегда равно положению.

Имя	Тип	Описание
position	string	Сущность Position

ErrorAdditionalInfo

Дополнительные сведения об ошибке управления ресурсами.

Имя	Тип	Описание
info	object	Дополнительные сведения.
type	string	Тип дополнительных сведений.

ErrorDetail

Сведения об ошибке.

Имя	Тип	Описание
additionalInfo	ErrorAdditionalInfo[]	Дополнительные сведения об ошибке.
code	string	Код ошибки.
details	ErrorDetail[]	Сведения об ошибке.
message	string	Сообщение об ошибке.
target	string	Целевой объект ошибки.

ErrorResponse

Сообщение об ошибке

Имя	Тип	Описание
error	ErrorDetail	Объект ошибки.

GeographicEntityType

Тип сущности Geography. Отображается только в том случае, если entityType был запрошен и доступен.

Имя	Тип	Описание
Country	string	название страны или региона
CountrySecondarySubdivision	string	Округ
CountrySubdivision	string	Область, республика, край
CountryTertiarySubdivision	string	Именованной области
Municipality	string	Город или город
MunicipalitySubdivision	string	Sub / Super City
Neighbourhood	string	Районе
PostalCodeArea	string	Почтовый индекс / почтовый индекс

LatLongPairAbbreviated

Расположение, представленное в виде широты и долготы с использованием коротких имен "lat" & "lon".

Имя	Тип	Описание
lat	number	Свойство Latitude
lon	number	Свойство Долгота

LocalizedMapView

Параметр View (также называемый параметром "регион пользователя") позволяет отображать правильные карты для определенной страны или региона для геополитически спорных регионов. Разные страны или регионы имеют разные представления таких регионов, и параметр View позволяет приложению соответствовать представлению, требуемому для страны или региона, который будет обслуживать приложение. По умолчанию параметр View имеет значение Unified, даже если он не определен в запросе. Вы несете ответственность за определение расположения пользователей, а затем правильное указание параметра View для этого расположения. Кроме того, можно задать параметр View=Auto, который будет возвращать данные карты на основе IP-адреса запроса. Параметр View в Azure Maps должен использоваться в соответствии с применимыми законами, включая те, которые касаются сопоставления, страны или региона, в которой доступны карты, изображения и другие данные и содержимое третьих лиц, доступ к которому вы имеете через Azure Maps. Пример: view=IN.

Дополнительные сведения и доступные представления см. в разделе Поддерживаемые представления.

Имя	Тип	Описание
AE	string	Объединенные Арабские Эмираты (арабское представление)
AR	string	Аргентина (аргентинское представление)
Auto	string	Данные карт возвращаются с учетом IP-адреса запроса.
BH	string	Бахрейн (арабское представление)
IN	string	Индия (индийское представление)
IQ	string	Ирак (арабское представление)
JO	string	Иордан (арабское представление)
KW	string	Кувейт (арабское представление)
LB	string	Ливан (арабское представление)
MA	string	Марокко (марокканское представление)
OM	string	Оман (арабское представление)
PK	string	Пакистан (пакистанское представление)
PS	string	Палестинская Автономия (арабское представление)
QA	string	Катар (арабское представление)
SA	string	Саудовская Аравия (арабское представление)
SY	string	Сирия (арабское представление)
Unified	string	Унифицированное представление (прочие)
YE	string	Йемен (арабское представление)

MatchType

Типы совпадений для операции обратного поиска адресов.

Имя	Тип	Описание
AddressPoint	string
HouseNumberRange	string
Street	string

QueryType

Тип возвращаемого запроса: NEARBY или NON_NEAR.

Имя	Тип	Описание
NEARBY	string	Поиск выполнялись вокруг определенной широты и долготы с определенным радиусом
NON_NEAR	string	Поиск выполняется глобально, без смещений на определенную широту и долготу, без определенного радиуса

ResponseFormat

Требуемый формат ответа. Значение может быть либо json , либо xml.

Имя	Тип	Описание
json	string	Формат обмена данными нотации объектов JavaScript
xml	string	Расширяемый язык разметки

ReverseSearchAddressResult

Этот объект возвращается из успешного обратного вызова Поиск Address

Имя	Тип	Описание
addresses	ReverseSearchAddressResultItem[]	Массив адресов
summary	SearchSummary	Объект Summary для обратного ответа Поиск Address

ReverseSearchAddressResultItem

Объект result для обратного ответа Поиск Address

Имя	Тип	Описание
address	Address	Адрес результата
matchType	MatchType	Сведения о типе соответствия. Одно из двух значений: AddressPoint HouseNumberRange Улица
position	string	Свойство Position в форме "{широта},{долгота}"
roadUse	RoadUseType[]	Описывает возможные способы использования дороги.

RoadUseType

Описывает возможные способы использования дороги.

Имя	Тип	Описание
Arterial	string
LimitedAccess	string
LocalStreet	string
Ramp	string
Rotary	string
Terminal	string

SearchSummary

Объект Summary для ответа API Поиск.

Имя	Тип	Описание
fuzzyLevel	integer	Максимальный уровень нечеткости, необходимый для предоставления результатов.
geoBias	LatLongPairAbbreviated	Указание того, что внутренняя поисковая система применила геопространственный уклон для улучшения ранжирования результатов. В некоторых методах на это можно повлиять, задав параметры lat и lon там, где они доступны. В других случаях это чисто внутренний.
limit	integer	Максимальное число ответов, которые будут возвращены
numResults	integer	Количество результатов в ответе.
offset	integer	Начальная смещение возвращаемых результатов в полном результирующем наборе.
query	string	Параметр запроса, который использовался для получения этих результатов поиска.
queryTime	integer	Время, затраченное на разрешение запроса, в миллисекундах.
queryType	QueryType	Тип возвращаемого запроса: NEARBY или NON_NEAR.
totalResults	integer	Общее число найденных результатов.

Поделиться через