Поиск расположения с помощью служб поиска Azure MapsSearch for a location using Azure Maps Search services

Azure Maps служба поиска — это набор интерфейсов API RESTful, предназначенных для поиска адресов, мест и бизнес-вхождений по имени, категории и другим географических сведениям.The Azure Maps Search Service is a set of RESTful APIs designed to help developers search addresses, places, and business listings by name, category, and other geographic information. Помимо поддержки традиционной геокодирования, службы также могут обращаться к геокодированным адресам и перекрестным улиц на основе широт и долгот.In addition to supporting traditional geocoding, services can also reverse geocode addresses and cross streets based on latitudes and longitudes. Значения широты и долготы, возвращаемые функцией поиска, можно использовать в качестве параметров в других Azure Maps служб, таких как Route и weather Services.Latitude and longitude values returned by the search can be used as parameters in other Azure Maps services, such as Route and Weather services.

В этой статье вы узнаете, как выполнять следующие задачи.In this article, you'll learn how to:

  • Запросите координаты широты и долготы для адреса (расположение геокода адреса) с помощью API поиска адреса.Request latitude and longitude coordinates for an address (geocode address location) by using the Search Address API.
  • Поиск адреса или точки интересов (достопримечательности) с помощью API нечеткого поиска.Search for an address or Point of Interest (POI) using the Fuzzy Search API.
  • Выполните обратный поиск адреса , чтобы перевести координатное расположение на почтовый адрес.Make a Reverse Address Search to translate coordinate location to street address.
  • Перевод координатного расположения в понятное для человека перекрестное почтовое размещение с помощью функции поиска обратный крест-адрес.Translate coordinate location into a human understandable cross street by using Search Address Reverse Cross Street API. Чаще всего это необходимо для отслеживания приложений, которые получают канал GPS с устройства или ресурса и хотят понять, где находится координата.Most often, this is needed in tracking applications that receive a GPS feed from a device or asset, and wish to know where the coordinate is located.

Предварительные требованияPrerequisites

  1. Создайте учетную запись службы Azure MapsMake an Azure Maps account
  2. Получите первичный ключ подписки, который иногда называется первичным ключом или ключом подписки.Obtain a primary subscription key, also known as the primary key or the subscription key.

В этом руководстве используется приложение Postman, но вы можете выбрать другую среду разработки API.This tutorial uses the Postman application, but you may choose a different API development environment.

Запрос широты и долготы для адреса (геокодирование)Request latitude and longitude for an address (geocoding)

В этом примере мы будем использовать API-интерфейс получения адреса поиска Azure Maps для преобразования адреса в координаты широты и долготы.In this example, we'll use the Azure Maps Get Search Address API to convert an address into latitude and longitude coordinates. Этот процесс также называется геокодированием .This process is also called geocoding . Кроме получения координат, ответ также возвращает подробные свойства адреса, такие как улица, почтовый индекс, орган власти и страна или регион.In addition to returning the coordinates, the response will also return detailed address properties such as street, postal code, municipality, and country/region information.

Совет

Если у вас есть набор адресов для геокодирования, можно использовать API пакетного поиска POST для отправки пакета запросов в одном вызове API.If you have a set of addresses to geocode, you can use the Post Search Address Batch API to send a batch of queries in a single API call.

  1. Откройте приложение Postman.Open the Postman app. В верхней части приложения Postman выберите элемент Создать .Near the top of the Postman app, select New . В окне Create New (Создание) выберите Collection (Коллекция).In the Create New window, select Collection . Присвойте имя коллекции и нажмите кнопку Создать .Name the collection and select the Create button. Эта коллекция будет использоваться для остальных примеров в этом документе.You'll use this collection for the rest of the examples in this document.

  2. Чтобы создать запрос, нажмите кнопку Создать еще раз.To create the request, select New again. В окне Create New (Создание) выберите Request (Запрос).In the Create New window, select Request . Введите Имя запроса для запроса.Enter a Request name for the request. Выберите коллекцию, созданную на предыдущем шаге, а затем нажмите кнопку Сохранить .Select the collection you created in the previous step, and then select Save .

  3. На вкладке Построитель выберите метод Get HTTP и введите следующий URL-адрес.Select the GET HTTP method in the builder tab and enter the following URL. В этом запросе мы ищем по определенному адресу: 400 Braod St, Seattle, WA 98109 .In this request, we're searching for a specific address: 400 Braod St, Seattle, WA 98109. Для этого запроса и других запросов, упомянутых в этой статье, замените {Azure-Maps-Primary-Subscription-key} первичным ключом подписки.For this request, and other requests mentioned in this article, replace {Azure-Maps-Primary-Subscription-key} with your primary subscription key.

    https://atlas.microsoft.com/search/address/json?&subscription-key={Azure-Maps-Primary-Subscription-key}&api-version=1.0&language=en-US&query=400 Broad St, Seattle, WA 98109
    
  4. Нажмите синюю кнопку Отправить .Click the blue Send button. Текст ответа будет содержать данные для одного расположения.The response body will contain data for a single location.

  5. Теперь мы будем искать в адресе несколько возможных расположений.Now, we'll search an address that has more than one possible locations. В разделе params измените значение query параметра на 400 Broad, Seattle .In the Params section, change the query key to 400 Broad, Seattle. Нажмите синюю кнопку Отправить .Click the blue Send button.

    Поиск адреса

  6. Затем попробуйте установить query ключ в значение 400 Broa .Next, try setting the query key to 400 Broa.

  7. Нажмите кнопку Отправить .Click the Send button. Теперь можно увидеть, что ответ содержит ответы из нескольких стран.You can now see that the response includes responses from multiple countries. Чтобы выполнить геосдвиг результатов в соответствующей области для пользователей, всегда добавляйте в запрос как можно больше сведений о местоположении.To geobias results to the relevant area for your users, always add as many location details as possible to the request.

Использование API нечеткого поискаUsing Fuzzy Search API

API Azure Maps нечеткий поиск поддерживает стандартные однострочные и поисковые запросы в свободной форме.The Azure Maps Fuzzy Search API supports standard single line and free-form searches. Рекомендуется использовать нечеткий API Azure Maps поиска, если пользовательский тип ввода для поискового запроса не известен.We recommend that you use the Azure Maps Search Fuzzy API when you don't know your user input type for a search request. Входные данные запроса могут быть полным или частичным адресом.The query input can be a full or partial address. Это также может быть маркер (достопримечательности), например имя достопримечательности, достопримечательности Category или имя торговой марки.It can also be a Point of Interest (POI) token, like a name of POI, POI category or name of brand. Кроме того, чтобы повысить релевантность результатов поиска, результаты запроса могут быть ограничены координатами и радиусом, или путем определения ограничивающего прямоугольника.Furthermore, to improve the relevance of your search results, the query results can be constrained by a coordinate location and radius, or by defining a bounding box.

Совет

Большинство запросов поиска по умолчанию maxFuzzyLevel = 1 для повышения производительности и уменьшения необычных результатов.Most Search queries default to maxFuzzyLevel=1 to gain performance and reduce unusual results. Уровни нечеткости можно настроить с помощью maxFuzzyLevel параметров или minFuzzyLevel .You can adjust fuzziness levels by using the maxFuzzyLevel or minFuzzyLevel parameters. Дополнительные сведения о maxFuzzyLevel и полный список всех необязательных параметров см. в разделе Параметры URI нечеткого поиска .For more information on maxFuzzyLevel and a complete list of all optional parameters, see Fuzzy Search URI Parameters

В этом примере мы будем использовать нечеткий поиск для поиска по всему миру pizza .In this example, we'll use Fuzzy Search to search the entire world for pizza. Затем мы покажем, как выполнить поиск по области определенной страны.Then, we'll show you how to search over the scope of a specific country. Наконец, мы покажем, как использовать координаты координат и RADIUS для определения области поиска в определенной области и ограничения числа возвращаемых результатов.Finally, we'll show you how to use a coordinate location and radius to scope a search over a specific area, and limit the number of returned results.

Важно!

Чтобы выполнить геосдвиг результатов в соответствующей области для пользователей, всегда добавляйте как можно больше сведений о расположении.To geobias results to the relevant area for your users, always add as many location details as possible. Дополнительные сведения см. в разделе рекомендации по поиску.To learn more, see Best Practices for Search.

  1. Откройте приложение POST, щелкните создать и выберите запрос .Open the Postman app, click New , and select Request . Введите Имя запроса для запроса.Enter a Request name for the request. Выберите коллекцию, созданную в предыдущем разделе, или создайте новую, а затем нажмите кнопку сохранить .Select the collection you created in the previous section or created a new one, and then select Save .

  2. На вкладке Построитель выберите метод Get HTTP и введите следующий URL-адрес.Select the GET HTTP method in the builder tab and enter the following URL. Для этого запроса и других запросов, упомянутых в этой статье, замените {Azure-Maps-Primary-Subscription-key} первичным ключом подписки.For this request, and other requests mentioned in this article, replace {Azure-Maps-Primary-Subscription-key} with your primary subscription key.

    https://atlas.microsoft.com/search/fuzzy/json?&api-version=1.0&subscription-key={Azure-Maps-Primary-Subscription-key}&language=en-US&query=pizza
    

    Примечание

    Атрибут json в URL-адресе пути определяет формат ответа.The json attribute in the URL path determines the response format. В этой статье для простоты использования и удобочитаемости используется JSON.This article uses json for ease of use and readability. Чтобы найти другие поддерживаемые форматы ответа, см format . Описание параметра в справочной документации по параметрам URI.To find other supported response formats, see the format parameter definition in the URI Parameter reference documentation.

  3. Щелкните Send (Отправить), а затем просмотрите текст ответа.Click Send and review the response body.

    Неоднозначная строка запроса для "пиццы" вернула 10- процентный результат (достопримечательности) в категориях "Пицца" и "Ресторан".The ambiguous query string for "pizza" returned 10 point of interest result (POI) in both the "pizza" and "restaurant" categories. Каждый результат включает такие сведения, как адрес улицы, значения широты и долготы, порт представления и точки входа для расположения.Each result includes details such as street address, latitude and longitude values, view port, and entry points for the location. Теперь результаты для этого запроса изменяются и не привязываются ни к одному ссылочному расположению.The results are now varied for this query, and are not tied to any reference location.

    На следующем шаге мы будем использовать countrySet параметр, чтобы указать только страны или регионы, для которых приложение нуждается в покрытии.In the next step, we'll use the countrySet parameter to specify only the countries/regions for which your application needs coverage. Полный список поддерживаемых стран и регионов см. в разделе Поиск покрытия.For a complete list of supported countries/regions, see Search Coverage.

  4. Поведение по умолчанию заключается в поиске по всему миру, потенциально возвращая ненужные результаты.The default behavior is to search the entire world, potentially returning unnecessary results. Далее мы будем искать пиццу только США.Next, we’ll search for pizza only the United States. Добавьте countrySet ключ в раздел params и задайте для него значение US .Add the countrySet key to the Params section, and set its value to US. Если задать countrySet для ключа значение, US результаты будут привязаны к США.Setting the countrySet key to US will bound the results to the United States.

    Поиск пиццы в США

    Теперь результаты ограничены кодом страны и запрос возвращает адреса пиццерий в США.The results are now bounded by the country code and the query returns pizza restaurants in the United States.

  5. Чтобы получить еще более целевой поиск, можно выполнить поиск по области lat./Лон.To get an even more targeted search, you can search over the scope of a lat./lon. пара координат.coordinate pair. В этом примере мы будем использовать lat./Лон..In this example, we'll use the lat./lon. Стрелки с пробелом в Сиэтле.of the Seattle Space Needle. Так как нам нужно только вернуть результаты в радиусе 400 метров, мы добавим radius параметр.Since we only want to return results within a 400-meters radius, we'll add the radius parameter. Кроме того, мы добавим limit параметр, чтобы ограничить результаты до пяти ближайших мест пиццы.Also, we'll add the limit parameter to limit the results to the five closest pizza places.

    В разделе params добавьте следующие пары "ключ-значение":In the Params section, add the following key/value pairs:

    КлавишиKey ЗначениеValue
    latlat 47,62052547.620525
    lonlon –122,349274-122.349274
    radiusradius 400400
    ограничениеlimit 55
  6. Нажмите кнопку Отправить .Click Send . Ответ содержит результаты для ресторанов в пицце рядом с пробелом в Сиэтле.The response includes results for pizza restaurants near the Seattle Space Needle.

Функция Azure Maps получить адрес поиска обратный API преобразует координаты в непонятные для человека адреса улицы.The Azure Maps Get Search Address Reverse API translates coordinates into human readable street addresses. Этот API часто используется для приложений, которые используют каналы GPS и хотят находить адреса в конкретных точках координат.This API is often used for applications that consume GPS feeds and want to discover addresses at specific coordinate points.

Важно!

Чтобы выполнить геосдвиг результатов в соответствующей области для пользователей, всегда добавляйте как можно больше сведений о расположении.To geobias results to the relevant area for your users, always add as many location details as possible. Дополнительные сведения см. в разделе рекомендации по поиску.To learn more, see Best Practices for Search.

Совет

Если у вас есть набор координатных расположений для обратного геокодирования, можно использовать обратный поиск адреса API для отправки пакета запросов в одном вызове API.If you have a set of coordinate locations to reverse geocode, you can use Post Search Address Reverse Batch API to send a batch of queries in a single API call.

В этом примере мы будем выполнять обратный поиск, используя несколько доступных необязательных параметров.In this example, we'll be making reverse searches using a few of the optional parameters that are available. Полный список необязательных параметров см. в разделе Параметры обратных результатов поиска.For the full list of optional parameters, see Reverse Search Parameters.

  1. В приложении POST щелкните создать и выберите запрос .In the Postman app, click New , and select Request . Введите Имя запроса для запроса.Enter a Request name for the request. Выберите коллекцию, созданную в первом разделе, или создайте новую, а затем нажмите кнопку сохранить .Select the collection you created in the first section or created a new one, and then select Save .

  2. На вкладке Построитель выберите метод Get HTTP и введите следующий URL-адрес.Select the GET HTTP method in the builder tab and enter the following URL. Для этого запроса и других запросов, упомянутых в этой статье, замените {Azure-Maps-Primary-Subscription-key} первичным ключом подписки.For this request, and other requests mentioned in this article, replace {Azure-Maps-Primary-Subscription-key} with your primary subscription key. Запрос должен выглядеть, как в этом URL-адресе:The request should look like the following URL:

    https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&subscription-key={Azure-Maps-Primary-Subscription-key}&language=en-US&query=47.591180,-122.332700&number=1
    
  3. Нажмите кнопку Отправить и проверьте текст ответа.Click Send , and review the response body. Вы должны увидеть один результат запроса.You should see one query result. Ответ включает основные сведения об адресе Safeco Field.The response includes key address information about Safeco Field.

  4. Теперь мы добавим следующие пары "ключ-значение" в раздел params :Now, we'll add the following key/value pairs to the Params section:

    КлавишиKey ЗначениеValue ВозвращаетReturns
    numbernumber 11 Ответ может включать сторону улицы (слева направо), а также смещение для числа.The response may include the side of the street (Left/Right) and also an offset position for the number.
    returnSpeedLimitreturnSpeedLimit truetrue Возвращает ограничение скорости по адресу.Returns the speed limit at the address.
    returnRoadUsereturnRoadUse truetrue Возвращает дорожные типы использования по адресу.Returns road use types at the address. Все возможные типы использования в пути см. в разделе типы использования дорожек.For all possible road use types, see Road Use Types.
    ретурнматчтипеreturnMatchType truetrue Возвращает тип соответствия.Returns the type of match. Все возможные значения см. в разделе обратные результаты поиска адресов .For all possible values, see Reverse Address Search Results

    Обратный поиск.

  5. Нажмите кнопку Отправить и проверьте текст ответа.Click Send , and review the response body.

  6. Далее мы добавим entityType ключ и присвоим ему значение Municipality .Next, we'll add the entityType key, and set its value to Municipality. entityTypeКлюч переопределит returnMatchType ключ на предыдущем шаге.The entityType key will override the returnMatchType key in the previous step. Также необходимо удалить returnSpeedLimit и, returnRoadUse так как мы запрашиваем сведения о органе государственной власти.We'll also need to remove returnSpeedLimit and returnRoadUse since we're requesting information about the municipality. Все возможные типы сущностей см. в разделе типы сущностей.For all possible entity types, see Entity Types.

    Поиск в обратных entityType.

  7. Нажмите кнопку Отправить .Click Send . Сравните результаты с результатами, возвращенными на шаге 5.Compare the results to the results returned in step 5. Так как запрошенный тип сущности теперь является municipality , ответ не включает сведения о почтовом адресе.Because the requested entity type is now municipality, the response does not include street address information. Кроме того, возвращаемое значение geometryId можно использовать для запроса многоугольника с помощью Azure Maps получения API-интерфейса Polygon поиска.Also, the returned geometryId can be used to request boundary polygon through Azure Maps Get Search Polygon API.

Совет

Дополнительные сведения об этих параметрах, а также сведения о других см. в разделе Параметры обратных результатов поиска.To get more information on these parameters, as well as to learn about others, see the Reverse Search Parameters section.

В этом примере мы будем искать перекрестные улицы на основе координат адреса.In this example, we'll search for a cross street based on the coordinates of an address.

  1. В приложении POST щелкните создать и выберите запрос .In the Postman app, click New , and select Request . Введите Имя запроса для запроса.Enter a Request name for the request. Выберите коллекцию, созданную в первом разделе, или создайте новую, а затем нажмите кнопку сохранить .Select the collection you created in the first section or created a new one, and then select Save .

  2. На вкладке Построитель выберите метод Get HTTP и введите следующий URL-адрес.Select the GET HTTP method in the builder tab and enter the following URL. Для этого запроса и других запросов, упомянутых в этой статье, замените {Azure-Maps-Primary-Subscription-key} первичным ключом подписки.For this request, and other requests mentioned in this article, replace {Azure-Maps-Primary-Subscription-key} with your primary subscription key. Запрос должен выглядеть, как в этом URL-адресе:The request should look like the following URL:

    https://atlas.microsoft.com/search/address/reverse/crossstreet/json?&api-version=1.0&subscription-key={Azure-Maps-Primary-Subscription-key}&language=en-US&query=47.591180,-122.332700
    

    Поиск по перекрестной улицы.

  3. Нажмите кнопку Отправить и проверьте текст ответа.Click Send , and review the response body. Обратите внимание, что ответ содержит crossStreet значение Occidental Avenue South .You'll notice that the response contains a crossStreet value of Occidental Avenue South.

Дальнейшие действияNext steps