Рекомендации по использованию службы поиска Azure MapsBest practices for Azure Maps Search Service

Azure Maps Служба поиска включает API-интерфейсы, которые предлагают различные возможности для поиска адресов, мест, Бизнес-вхождений по имени или категории, а также другие географические сведения.Azure Maps Search Service includes APIs that offer various capabilities to help developers to search addresses, places, business listings by name or category, and other geographic information. Например,API нечеткого поиска позволяет пользователям искать адрес или интересующую точку (достопримечательности).For example,Fuzzy Search API allows users to search for an address or Point of Interest (POI).

В этой статье объясняется, как применять различные полезные методики при обращении к данным из службы поиска Azure Maps.This article explains how to apply sound practices when you call data from Azure Maps Search Service. Вы узнаете, как:You'll learn how to:

  • Построение запросов для возврата релевантных соответствийBuild queries to return relevant matches
  • Сужение результатов поискаLimit search results
  • Сведения о различиях между типами результатовLearn the differences between result types
  • Чтение структуры "Поиск адреса-ответ"Read the address search-response structure

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

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

В этой статье используется приложение POST для создания вызовов RESTful, но можно выбрать любую среду разработки API.This article uses the Postman app to build REST calls, but you can choose any API development environment.

Рекомендации по геокодированию адресовBest practices to geocode addresses

При поиске полного или частичного адреса с помощью службы поиска Azure Maps программный интерфейс API считывает ключевые слова из вашего поискового запроса.When you search for a full or partial address by using Azure Maps Search Service, the API reads keywords from your search query. После этого он возвращает координаты долготы и широты нужного адреса.Then it returns the longitude and latitude coordinates of the address. Этот процесс называется геокодированием .This process is called geocoding .

Возможность геокодирования в стране (регионе) зависит от доступности данных о дорогах и точности работы службы геокодирования.The ability to geocode in a country/region depends on the availability of road data and the precision of the geocoding service. Дополнительные сведения о возможностях геокодирования Azure Maps в различных странах или регионах см. в разделе Наличие информации о геокодировании.For more information about Azure Maps geocoding capabilities by country or region, see Geocoding coverage.

Сужение результатов поискаLimit search results

API поиска Azure Maps позволяет сужать результаты поиска необходимым образом.Azure Maps Search API can help you limit search results appropriately. Результаты следует сужать, чтобы ваши пользователи видели только релевантные данные.You limit results so that you can display relevant data to your users.

Примечание

API поиска поддерживают больше параметров, чем описано в этой статье.The search APIs support more parameters than just the ones that this article discusses.

Географически уточненные результаты поискаGeobiased search results

Чтобы уточнить результаты для нужной пользователю географической области, всегда добавляйте как можно больше сведений о расположении.To geobias results to the relevant area for your user, always add as many location details as possible. Для этого вам может потребоваться сузить результаты поиска, указав некоторые типы входных данных:You might want to restrict the search results by specifying some input types:

  • Задайте параметр countrySet.Set the countrySet parameter. Например, установите для него значение US,FR.You can set it to US,FR, for example. По умолчанию API выполняет поиск по всему миру, поэтому он может давать нерелевантные результаты.By default, the API searches the entire world, so it can return unnecessary results. Если в запросе нет параметра countrySet, результаты поиска могут оказаться неточными.If your query has no countrySet parameter, then the search might return inaccurate results. Например, при поиске города с именем Бельвью (Bellevue) возвращаются результаты для США и Франции, так как в обеих этих странах есть город с именем Бельвью .For example, a search for a city named Bellevue returns results from the USA and France because both countries/regions contain a city named Bellevue .

  • Для задания ограничивающего прямоугольника можно использовать параметры btmRight и topleft.You can use the btmRight and topleft parameters to set the bounding box. Эти параметры ограничивают поиск определенной областью на карте.These parameters restrict the search to a specific area on the map.

  • Чтобы влиять на область релевантности результатов, определите параметры координат — lat и lon.To influence the area of relevance for the results, define the lat and lon coordinate parameters. Чтобы задать радиус области поиска, используйте параметр radius.Use the radius parameter to set the radius of the search area.

Параметры поиска по нечеткому соответствиюFuzzy search parameters

API-интерфейс Search Fuzzy Azure Maps рекомендуется использовать, если вы не знаете, какие входные данные введены пользователем в поисковом запросе.We recommend that you use the Azure Maps Search Fuzzy API when you don't know your user inputs for a search query. Например, входные данные пользователя могут быть адресом или типом интересующей вас точки (достопримечательности), например " Покупка Mall ".For example, input from the user could be an address or the type of Point of Interest (POI), like shopping mall . API-интерфейс объединяет поиск точек интереса и геокодирование в канонический однострочный поиск :The API combines POI searching and geocoding into a canonical single-line search :

  • Параметры minFuzzyLevel и maxFuzzyLevel позволяют выдавать релевантные результаты даже в том случае, если параметры запроса не точно соответствуют необходимой пользователю информации.The minFuzzyLevel and maxFuzzyLevel parameters help return relevant matches even when query parameters don't exactly match the information that the user wants. Чтобы повысить качество поиска и сократить число нерелевантных результатов, задайте для поисковых запросов значения по умолчанию — minFuzzyLevel=1 и maxFuzzyLevel=2.To maximize performance and reduce unusual results, set search queries to defaults of minFuzzyLevel=1 and maxFuzzyLevel=2.

    Например, если для параметра maxFuzzyLevel задано значение 2, поисковый запрос рестран будет соответствовать слову ресторан .For example, when the maxFuzzyLevel parameter is set to 2, the search term restrant is matched to restaurant . При необходимости уровни нечеткого соответствия, используемые по умолчанию, можно изменить.You can override the default fuzzy levels when you need to.

  • Используйте параметр idxSet, чтобы задать приоритет для точного набора типов результатов.Use the idxSet parameter to prioritize the exact set of result types. Чтобы задать приоритет для точного набора результатов, можно отправить разделенный запятыми список индексов.To prioritize an exact set of results, you can submit a comma-separated list of indexes. Порядок элементов в списке не имеет значения.In your list, the item order doesn't matter. Azure Maps поддерживает следующие индексы.Azure Maps supports the following indexes:

  • Addr - Диапазоны адресов . Адресные точки, которые интерполируются с начала и с конца улицы.Addr - Address ranges : Address points that are interpolated from the beginning and end of the street. Эти точки представляются в виде диапазонов адресов.These points are represented as address ranges.

  • Geo - Географические регионы . Административно-территориальные единицы страны.Geo - Geographies : Administrative divisions of land. Географическим регионом, например, может быть страна, регион, штат или город.A geography can be a country/region, state, or city, for example.

  • PAD - Точечные адреса . Адреса, содержащие название улицы и номер дома.PAD - Point addresses : Addresses that include a street name and number. Точечные адреса могут находиться в индексе.Point addresses can be found in an index. Например, Soquel Dr 2501 .An example is Soquel Dr 2501 . Это самый высокий уровень точности для адресов.A point address provides the highest level of accuracy available for addresses.

  • POI - Достопримечательности . Точки на карте, которые считаются интересными или заслуживающими внимания.POI - Points of interest : Points on a map that are considered to be worth attention or that might be interesting. API Search Address не возвращает расположения достопримечательностей.The Search Address API doesn't return POIs.

  • Str - Улицы . Улицы на карте.Str - Streets : Streets on the map.

  • XStr - Перекрестки . Точки пересечения двух улиц.XStr - Cross streets or intersections : Junctions or places where two streets intersect.

Примеры использованияUsage examples

  • idxSet=POI — поиск только достопримечательностей.idxSet=POI - Search POIs only.

  • idxSet=PAD,Addr — поиск только адресов.idxSet=PAD,Addr - Search addresses only. PAD указывает точечный адрес, Addr указывает диапазон адресов.PAD indicates the point address, and Addr indicates the address range.

Обратное геокодирование и фильтр по типу сущности географических регионовReverse-geocode and filter for a geography entity type

При выполнении поиска с обратным геокодированием с помощью API-интерфейса Search Address Reverse служба может возвращать полигональные контуры административных областей.When you do a reverse-geocode search in the Search Address Reverse API, the service can return polygons for administrative areas. Например, может потребоваться получить многоугольник области для города.For example, you might want to fetch the area polygon for a city.  Чтобы сузить область поиска до конкретных типов сущности географических регионов, включите в запрос параметр entityType.To narrow the search to specific geography entity types, include the entityType parameter in your requests.

Полученный ответ будет содержать идентификатор географического региона и соответствующий тип сущности.The resulting response contains the geography ID and the entity type that was matched. Если указать более одной сущности, конечная точка вернет наименьшую доступную сущность .If you provide more than one entity, then the endpoint returns the smallest entity available . Полученный геометрический идентификатор можно использовать для получения геометрического вида географического региона через службу Search Polygon.You can use the returned geometry ID to get the geography's geometry through the Search Polygon service.

Пример запросаSample request

https://atlas.microsoft.com/search/address/reverse/json?api-version=1.0&subscription-key={subscription-key}&query=47.6394532,-122.1304551&language=en-US&entityType=Municipality

ОтветResponse

{
    "summary": {
        "queryTime": 14,
        "numResults": 1
    },
    "addresses": [
        {
            "address": {
                "routeNumbers": [],
                "countryCode": "US",
                "countrySubdivision": "WA",
                "countrySecondarySubdivision": "King",
                "countryTertiarySubdivision": "Seattle East",
                "municipality": "Redmond",
                "country": "United States",
                "countryCodeISO3": "USA",
                "countrySubdivisionName": "Washington"
            },
            "position": "47.639454,-122.130455",
            "dataSources": {
                "geometry": {
                    "id": "00005557-4100-3c00-0000-0000596ae571"
                }
            },
            "entityType": "Municipality"
        }
    ]
}

Задание языка результатовSet the results language

Чтобы задать язык выдаваемых результатов поиска, используйте параметр language.Use the language parameter to set the language for the returned search results. Если для запроса язык не задан, по умолчанию служба поиска использует наиболее распространенный язык в данной стране или данном регионе.If the request doesn't set the language, then by default Search Service uses the most common language in the country or region. Если данные на указанном языке не доступны, используется язык по умолчанию.When no data is available in the specified language, the default language is used.

Дополнительные сведения см. в разделе Поддерживаемые языки в службе Azure Maps.For more information, see Azure Maps supported languages.

Использование режима прогнозирования (автоматических рекомендаций)Use predictive mode (automatic suggestions)

Чтобы найти дополнительные результаты для частичных запросов, задайте для параметра typeahead значение true.To find more matches for partial queries, set the typeahead parameter to true. Такой запрос будет интерпретироваться как запрос с частичными входными данными, а поиск перейдет в режим прогнозирования.This query is interpreted as a partial input, and the search enters predictive mode. Если не задать для параметра typeahead значение true, служба будет предполагать, что ей передана вся необходимая информация.If you don't set the typeahead parameter to true, then the service assumes that all relevant information has been passed in.

В указанном ниже примере службе поиска адреса передается запрос Microso .In the following sample query, the Search Address service is queried for Microso . Здесь для параметра typeahead задается значение true.Here, the typeahead parameter set to true. Ответ показывает, что служба поиска интерпретировала этот запрос как частичный.The response shows that the search service interpreted the query as partial query. Ответ содержит результаты для автоматически предположенного запроса.The response contains results for an automatically suggested query.

Пример запросаSample query

https://atlas.microsoft.com/search/address/json?subscription-key={subscription-key}&api-version=1.0&typeahead=true&countrySet=US&lat=47.6370891183&lon=-122.123736172&query=Microsoft

ОтветResponse

{
    "summary": {
        "query": "microsoft",
        "queryType": "NON_NEAR",
        "queryTime": 18,
        "numResults": 7,
        "offset": 0,
        "totalResults": 7,
        "fuzzyLevel": 1,
        "geoBias": {
            "lat": 47.6370891183,
            "lon": -122.123736172
        }
    },
    "results": [
        {
            "type": "Street",
            "id": "US/STR/p0/9438784",
            "score": 2.594099998474121,
            "dist": 314.0590106663596,
            "address": {
                "streetName": "Microsoft Way",
                "municipalitySubdivision": "Redmond",
                "municipality": "Redmond",
            },
            "position": {
                "lat": 47.63988,
                "lon": -122.12438
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.64223,
                    "lon": -122.1256,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.63748,
                    "lon": -122.12309,
                    "valid": true
                }
            }
        },
        {
            "type": "Street",
            "id": "US/STR/p0/1756074",
            "score": 2.592679977416992,
            "dist": 876.0272035824189,
            "address": {
                "streetName": "Microsoft Road",
                "municipalitySubdivision": "Redmond",
                "municipality": "Redmond",
                "countrySecondarySubdivision": "King",
                "countryTertiarySubdivision": "Seattle East",
                "countrySubdivision": "WA",
                "countrySubdivisionName": "Washington",
                "postalCode": "98052",
                "countryCode": "US",
                "country": "United States",
                "countryCodeISO3": "USA",
                "freeformAddress": "Microsoft Road, Redmond, WA 98052"
            },
            "position": {
                "lat": 47.64032,
                "lon": -122.1344
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.64253,
                    "lon": -122.13535,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.63816,
                    "lon": -122.13305,
                    "valid": true
                }
            }
        },
        {
            "type": "Street",
            "id": "US/STR/p0/1470668",
            "score": 2.5290400981903076,
            "dist": 2735.4883918101486,
            "address": {
                "streetName": "Microsoft West Campus Road",
                "municipalitySubdivision": "Redmond",
                "municipality": "Bellevue",
                "countrySecondarySubdivision": "King",
                "countryTertiarySubdivision": "Seattle East",
                "countrySubdivision": "WA",
                "countrySubdivisionName": "Washington",
                "postalCode": "98007",
                "countryCode": "US",
                "country": "United States",
                "countryCodeISO3": "USA",
                "freeformAddress": "Microsoft West Campus Road, Bellevue, WA 98007"
            },
            "position": {
                "lat": 47.65784,
                "lon": -122.14335
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.65785,
                    "lon": -122.14335,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.65784,
                    "lon": -122.14325,
                    "valid": true
                }
            }
        },
        {
            "type": "Street",
            "id": "US/STR/p0/12812615",
            "score": 2.527509927749634,
            "dist": 2870.9579016916873,
            "address": {
                "streetName": "Microsoft West Campus Road",
                "municipalitySubdivision": "Redmond",
                "municipality": "Redmond",
                "countrySecondarySubdivision": "King",
                "countryTertiarySubdivision": "Seattle East",
                "countrySubdivision": "WA",
                "countrySubdivisionName": "Washington",
                "postalCode": "98052",
                "countryCode": "US",
                "country": "United States",
                "countryCodeISO3": "USA",
                "freeformAddress": "Microsoft West Campus Road, Redmond, WA 98052"
            },
            "position": {
                "lat": 47.66034,
                "lon": -122.1404
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.66039,
                    "lon": -122.14325,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.65778,
                    "lon": -122.13749,
                    "valid": true
                }
            }
        },
        {
            "type": "Street",
            "id": "US/STR/p0/197588",
            "score": 2.4630401134490967,
            "dist": 878.1404663812472,
            "address": {
                "streetName": "157th Avenue Northeast",
                "municipalitySubdivision": "Redmond",
                "municipality": "Redmond",
                "countrySecondarySubdivision": "King",
                "countryTertiarySubdivision": "Seattle East",
                "countrySubdivision": "WA",
                "countrySubdivisionName": "Washington",
                "postalCode": "98052",
                "extendedPostalCode": "980525344, 980525398, 980525399",
                "countryCode": "US",
                "country": "United States",
                "countryCodeISO3": "USA",
                "freeformAddress": "157th Avenue Northeast, Redmond, WA 98052"
            },
            "position": {
                "lat": 47.64351,
                "lon": -122.13056
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.64473,
                    "lon": -122.13058,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.6425,
                    "lon": -122.13016,
                    "valid": true
                }
            }
        },
        {
            "type": "Street",
            "id": "US/STR/p0/3033991",
            "score": 2.0754499435424805,
            "dist": 3655467.8844475765,
            "address": {
                "streetName": "Microsoft Way",
                "municipalitySubdivision": "Yorkmount, Charlotte",
            },
            "position": {
                "lat": 35.14267,
                "lon": -80.91824
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 35.14287,
                    "lon": -80.91839,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 35.14267,
                    "lon": -80.91814,
                    "valid": true
                }
            }
        },
        {
            "type": "Street",
            "id": "US/STR/p0/8395877",
            "score": 2.0754499435424805,
            "dist": 3655437.0037482483,
            "address": {
                "streetName": "Microsoft Way",
                "municipalitySubdivision": "Charlotte",
                "municipality": "Charlotte",
                "countrySecondarySubdivision": "Mecklenburg",
                "countryTertiarySubdivision": "Township 1 Charlotte",
                "countrySubdivision": "NC",
                "countrySubdivisionName": "North Carolina",
                "postalCode": "28273",
                "extendedPostalCode": "282738105, 282738106, 282738108, 2827382, 282738200",
                "countryCode": "US",
                "country": "United States",
                "countryCodeISO3": "USA",
                "freeformAddress": "Microsoft Way, Charlotte, NC 28273"
            },
            "position": {
                "lat": 35.14134,
                "lon": -80.9198
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 35.14274,
                    "lon": -80.92159,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 35.14002,
                    "lon": -80.91824,
                    "valid": true
                }
            }
        }
    ]
}

Кодирование URI-кода для работы со специальными символамиEncode a URI to handle special characters

Чтобы найти адреса перекрестков, необходимо закодировать универсальный код ресурса (URI) для работы со специальными символами в адресе.To find cross street addresses, you must encode the URI to handle special characters in the address. Рассмотрим следующий пример адреса: 1st Avenue & Union Street, Seattle (1-я авеню и Юнион-стрит, Сиэтл).Consider this address example: 1st Avenue & Union Street, Seattle . В данном случае перед отправкой запроса необходимо закодировать символ амперсанда (&).Here, encode the ampersand character (&) before you send the request.

Рекомендуется кодировать символьные данные в URI-кодах.We recommend that you encode character data in a URI. В URI-кодах все специальные символы кодируются с помощью знака процента (%) и двузначного шестнадцатеричного значения, соответствующего коду данного символа в кодировке UTF-8.In a URI, you encode all characters by using a percentage sign (%) and a two-character hexadecimal value that corresponds to the characters' UTF-8 code.

Примеры использованияUsage examples

Начнем с этого адреса:Start with this address:

query=1st Avenue & E 111th St, New York

Закодируем адрес:Encode the address:

query=1st%20Avenue%20%26%20E%20111th%20St%2C%20New%20York

Можно использовать следующие методы.You can use the following methods.

JavaScript или TypeScript:JavaScript or TypeScript:

encodeURIComponent(query)

C# или Visual Basic:C# or Visual Basic:

Uri.EscapeDataString(query)

Java:Java:

URLEncoder.encode(query, "UTF-8") 

Python:Python:

import urllib.parse 
urllib.parse.quote(query)

C++:C++:

#include <curl/curl.h>
curl_easy_escape(query)

PHP.PHP:

urlencode(query)

Ruby:Ruby:

CGI::escape(query) 

Swift:Swift:

query.stringByAddingPercentEncodingWithAllowedCharacters(.URLHostAllowedCharacterSet()) 

Go:Go:

import ("net/url") 
url.QueryEscape(query)

Рекомендации по поиску точек интересаBest practices for POI searching

При поиске точек интереса результаты можно запрашивать по названию точек интереса.In a POI search, you can request POI results by name. Например, можно искать компанию по ее названию.For example, you can search for a business by name.

Мы настоятельно рекомендуем использовать параметр countrySet для указания стран или регионов, которые должно охватывать ваше приложение.We strongly recommend that you use the countrySet parameter to specify countries/regions where your application needs coverage. По умолчанию поиск ведется по всему миру.The default behavior is to search the entire world. Это слишком широкий поиск, и он может дать ненужные результаты, а также занять много времени.This broad search might return unnecessary results, and the search might take a long time.

Для улучшения релевантности результатов и данных при поиске точек интереса ответ на поисковый запрос содержит сведения о торговых марках.To improve the relevance of the results and the information in the response, a POI search response includes brand information. Эти сведения можно использовать при дальнейшем анализе ответа.You can use this information to further to parse the response.

При отправке запроса можно указать разделенный запятыми список торговых марок.In a request, you can submit a comma-separated list of brand names. Используйте этот список, чтобы сузить результаты до набора конкретных торговых марок путем задания параметра brandSet.Use the list to restrict the results to specific brands by setting the brandSet parameter. Порядок элементов в списке не имеет значения.In your list, item order doesn't matter. Когда вы указываете несколько списков торговых марок, возвращаемые результаты должны соответствовать по крайней мере одному из ваших списков.When you provide multiple brand lists, the results that are returned must belong to at least one of your lists.

Чтобы изучить поиск торговых марок, давайте создадим запрос на поиск по категориям точек интереса.To explore brand searching, let's make a POI category search request. В указанном ниже примере мы ищем заправочные станции рядом с кампусом Майкрософт в Редмонде, штат Вашингтон.In the following example, we look for gas stations near the Microsoft campus in Redmond, Washington. В ответе содержатся сведения о торговой марке для каждой найденной точки интереса.The response shows brand information for each POI that was returned.

Пример запросаSample query

https://atlas.microsoft.com/search/poi/json?subscription-key={subscription-key}&api-version=1.0&query=gas%20station&limit=3&lat=47.6413362&lon=-122.1327968

ОтветResponse

{
    "summary": {
        "query": "gas station",
        "queryType": "NON_NEAR",
        "queryTime": 276,
        "numResults": 3,
        "offset": 0,
        "totalResults": 762680,
        "fuzzyLevel": 1,
        "geoBias": {
            "lat": 47.6413362,
            "lon": -122.1327968
        }
    },
    "results": [
        {
            "type": "POI",
            "id": "US/POI/p0/8831765",
            "score": 5.6631999015808105,
            "dist": 1037.0280221303253,
            "info": "search:ta:840531000004190-US",
            "poi": {
                "name": "Chevron",
                "phone": "+(1)-(425)-6532200",
                "brands": [
                    {
                        "name": "Chevron"
                    }
                ],
                "categorySet": [
                    {
                        "id": 7311
                    }
                ],
                "url": "www.chevron.com",
                "categories": [
                    "petrol station"
                ],
                "classifications": [
                    {
                        "code": "PETROL_STATION",
                        "names": [
                            {
                                "nameLocale": "en-US",
                                "name": "petrol station"
                            }
                        ]
                    }
                ]
            },
            "address": {
                "streetNumber": "2444",
                "streetName": "Bel Red Rd",
                "municipalitySubdivision": "Northeast Bellevue, Bellevue",
            },
            "position": {
                "lat": 47.63201,
                "lon": -122.13281
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.63291,
                    "lon": -122.13414,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.63111,
                    "lon": -122.13148,
                    "valid": true
                }
            },
            "entryPoints": [
                {
                    "type": "main",
                    "position": {
                        "lat": 47.63222,
                        "lon": -122.13312,
                        "valid": true
                    }
                }
            ]
        },
        {
            "type": "POI",
            "id": "US/POI/p0/8831752",
            "score": 5.662710189819336,
            "dist": 1330.1278248163273,
            "info": "search:ta:840539001100326-US",
            "poi": {
                "name": "76",
                "phone": "+(1)-(425)-7472126",
                "brands": [
                    {
                        "name": "76"
                    }
                ],
                "categorySet": [
                    {
                        "id": 7311
                    }
                ],
                "url": "www.76.com",
                "categories": [
                    "petrol station"
                ],
                "classifications": [
                    {
                        "code": "PETROL_STATION",
                        "names": [
                            {
                                "nameLocale": "en-US",
                                "name": "petrol station"
                            }
                        ]
                    }
                ]
            },
            "address": {
                "streetNumber": "2421",
                "streetName": "148Th Ave Ne",
                "municipalitySubdivision": "Redmond, Bridle Trails, Bellevue",
                "municipality": "Redmond, Bellevue",
                "countrySecondarySubdivision": "King",
                "countryTertiarySubdivision": "Seattle East",
                "countrySubdivision": "WA",
                "countrySubdivisionName": "Washington",
                "postalCode": "98007",
                "countryCode": "US",
                "country": "United States",
                "countryCodeISO3": "USA",
                "freeformAddress": "2421 148Th Ave Ne, Bellevue, WA 98007",
                "localName": "Bellevue"
            },
            "position": {
                "lat": 47.63187,
                "lon": -122.14365
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.63277,
                    "lon": -122.14498,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.63097,
                    "lon": -122.14232,
                    "valid": true
                }
            },
            "entryPoints": [
                {
                    "type": "minor",
                    "position": {
                        "lat": 47.63187,
                        "lon": -122.14374,
                        "valid": true
                    }
                },
                {
                    "type": "main",
                    "position": {
                        "lat": 47.63186,
                        "lon": -122.14313,
                        "valid": true
                    }
                }
            ]
        },
        {
            "type": "POI",
            "id": "US/POI/p0/8831764",
            "score": 5.662449836730957,
            "dist": 1458.645407416307,
            "info": "search:ta:840539000488527-US",
            "poi": {
                "name": "BROWN BEAR CAR WASH",
                "phone": "+(1)-(425)-6442868",
                "brands": [
                    {
                        "name": "Texaco"
                    }
                ],
                "categorySet": [
                    {
                        "id": 7311
                    }
                ],
                "url": "www.texaco.com/",
                "categories": [
                    "petrol station"
                ],
                "classifications": [
                    {
                        "code": "PETROL_STATION",
                        "names": [
                            {
                                "nameLocale": "en-US",
                                "name": "petrol station"
                            }
                        ]
                    }
                ]
            },
            "address": {
                "streetNumber": "15248",
                "streetName": "Bel Red Rd",
                "municipalitySubdivision": "Redmond",
            },
            "position": {
                "lat": 47.62843,
                "lon": -122.13628
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.62933,
                    "lon": -122.13761,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.62753,
                    "lon": -122.13495,
                    "valid": true
                }
            },
            "entryPoints": [
                {
                    "type": "main",
                    "position": {
                        "lat": 47.62827,
                        "lon": -122.13628,
                        "valid": true
                    }
                }
            ]
        }
    ]
}

С помощью API поиска точек интереса вы можете искать аэропорты, используя их официальные коды.By using the Search POI API, you can look for airports by using their official code. Например, для поиска международного аэропорта Сиэтл/Такома можно использовать код SEA :For example, you can use SEA to find the Seattle-Tacoma International Airport:

https://atlas.microsoft.com/search/poi/json?subscription-key={subscription-key}&api-version=1.0&query=SEA 

Для поиска точек интереса в окрестностях определенного места можно попытаться использовать API-интерфейс Search Nearby.To retrieve POI results around a specific location, you can try using the Search Nearby API. Конечная точка возвращает только результаты, касающиеся точек интереса.The endpoint returns only POI results. Она не воспринимает параметры поискового запроса.It doesn't take in a search query parameter.

Чтобы сузить результаты поиска, рекомендуется задать радиус поиска.To limit the results, we recommend that you set the radius.

Основные сведения об ответахUnderstanding the responses

Давайте найдем нужный адрес в Сиэтле, отправив запрос на поиск адреса службе поиска Azure Maps.Let's find an address in Seattle by making an address-search request to the Azure Maps Search Service. В следующем URL-адресе запроса мы задаем для параметра countrySet значение US, чтобы искать нужный адрес в США.In the following request URL, we set the countrySet parameter to US to search for the address in the USA.

Пример запросаSample query

https://atlas.microsoft.com/search/address/json?subscription-key={subscription-key}&api-version=1&query=400%20Broad%20Street%2C%20Seattle%2C%20WA&countrySet=US

Поддерживаемые типы результатовSupported types of results

  • Точечный адрес . Точка на карте с определенным адресом, содержащим название улицы и номер дома.Point Address : Points on a map that have a specific address with a street name and number. Это самый высокий уровень точности для адресов.Point Address provides the highest level of accuracy for addresses.

  • Диапазон адресов . Диапазон адресных точек, которые интерполируются с начала и с конца улицы.Address Range : The range of address points that are interpolated from the beginning and end of the street.

  • Geography . Области на карте, соответствующие административно-территориальным единицам страны (например, страна, регион, штат или город).Geography : Areas on a map that represent administrative divisions of a land, for example, country/region, state, or city.

  • Точка интереса . Точки на карте, которые считаются интересными или заслуживающими внимания.POI : Points on a map that are worth attention and that might be interesting.

  • Улица . Улицы на карте.Street : Streets on the map. Адреса приводятся к координатам широты и долготы улицы, на которой находится указанный адрес.Addresses are resolved to the latitude and longitude coordinates of the street that contains the address. Номера домов могут не учитываться.The house number might not be processed.

  • Перекресток . Пересечения улиц.Cross Street : Intersections. Перекресток — место пересечения двух улиц.Cross streets represent junctions where two streets intersect.

ОтветResponse

Давайте рассмотрим структуру ответа.Let's look at the response structure. В указанном ниже ответе типы результирующих объектов отличаются друг от друга.In the response that follows, the types of the result objects are different. Если вы посмотрите внимательно, то увидите три типа результирующих объектов.If you look carefully, you see three types of result objects:

  • Точечный адресPoint Address
  • УлицаStreet
  • ПерекрестокCross Street

Обратите внимание, что поиск по адресу не дает результаты по точкам интереса.Notice that the address search doesn't return POIs.

Параметр Score для каждого объекта ответа указывает, как показатель соответствия соотносится с аналогичными показателями других объектов в том же ответе.The Score parameter for each response object indicates how the matching score relates to the scores of other objects in the same response. Дополнительные сведения о параметрах объекта ответа см. в разделе Получение API Search Address.For more information about response object parameters, see Get Search Address.

{
    "summary": {
        "query": "400 broad street seattle wa",
        "queryType": "NON_NEAR",
        "queryTime": 146,
        "numResults": 6,
        "offset": 0,
        "totalResults": 7,
        "fuzzyLevel": 1
    },
    "results": [
        {
            "type": "Point Address",
            "id": "US/PAD/p0/28725082",
            "score": 9.893799781799316,
            "address": {
                "streetNumber": "400",
                "streetName": "Broad Street",
            },
            "position": {
                "lat": 47.62039,
                "lon": -122.34928
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.62129,
                    "lon": -122.35061,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.61949,
                    "lon": -122.34795,
                    "valid": true
                }
            },
            "entryPoints": [
                {
                    "type": "main",
                    "position": {
                        "lat": 47.61982,
                        "lon": -122.34886,
                        "valid": true
                    }
                }
            ]
        },
        {
            "type": "Street",
            "id": "US/STR/p0/6700384",
            "score": 8.129190444946289,
            "address": {
                "streetName": "Broad Street",
            },
            "position": {
                "lat": 47.61724,
                "lon": -122.35207
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.61825,
                    "lon": -122.35336,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.61626,
                    "lon": -122.35078,
                    "valid": true
                }
            }
        },
        {
            "type": "Street",
            "id": "US/STR/p0/9701953",
            "score": 8.129190444946289,
            "address": {
                "streetName": "Broad Street",
            },
            "position": {
                "lat": 47.61965,
                "lon": -122.349
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.62066,
                    "lon": -122.35041,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.61857,
                    "lon": -122.34761,
                    "valid": true
                }
            }
        },
        {
            "type": "Street",
            "id": "US/STR/p0/11721297",
            "score": 8.129190444946289,
            "address": {
                "streetName": "Broad Street",
                "municipalitySubdivision": "Seattle, Downtown Seattle, Denny Regrade, Belltown",
                "municipality": "Seattle",
                "countrySecondarySubdivision": "King",
                "countryTertiarySubdivision": "Seattle",
                "countrySubdivision": "WA",
                "countrySubdivisionName": "Washington",
                "postalCode": "98121",
                "extendedPostalCode": "981211237",
                "countryCode": "US",
                "country": "United States",
                "countryCodeISO3": "USA",
                "freeformAddress": "Broad Street, Seattle, WA 98121"
            },
            "position": {
                "lat": 47.61825,
                "lon": -122.35078
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.61857,
                    "lon": -122.35078,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.61825,
                    "lon": -122.35041,
                    "valid": true
                }
            }
        },
        {
            "type": "Cross Street",
            "id": "US/XSTR/p1/232144",
            "score": 6.754479885101318,
            "address": {
                "streetName": "Broad Street & Valley Street",
                "municipalitySubdivision": "South Lake Union, Seattle",
            },
            "position": {
                "lat": 47.62545,
                "lon": -122.33974
            },
            "viewport": {
                "topLeftPoint": {
                    "lat": 47.62635,
                    "lon": -122.34107,
                    "valid": true
                },
                "btmRightPoint": {
                    "lat": 47.62455,
                    "lon": -122.33841,
                    "valid": true
                }
            }
        }
    ]
}

GeometryGeometry

Ответ типа Geometry может содержать геометрический идентификатор, возвращаемый в объекте dataSources через параметры geometry и id.A response type of Geometry can include the geometry ID that's returned in the dataSources object under geometry and id. Например, вы можете использовать службу Search Polygon для запроса геометрических данных в формате GeoJSON.For example, you can use the Search Polygon service to request the geometry data in a GeoJSON format. С помощью этого формата можно получить контур города или аэропорта для нужного набора сущностей.By using this format, you can get a city or airport outline for a set of entities. Затем эти данные о границах можно использовать для настройки геозоны или поиска точек интереса в пределах заданного геометрического контура.You can then use this boundary data to Set up a geofence or Search POIs inside the geometry.

Ответы на обращения к API-интерфейсу Search Address или Search Fuzzy могут содержать геометрический идентификатор, возвращаемый в объекте dataSources через параметры geometry и id:Responses for the Search Address API or the Search Fuzzy API can include the geometry ID that's returned in the dataSources object under geometry and id:

"dataSources": { 
        "geometry": { 
            "id": "00005557-4100-3c00-0000-000059690938" // The geometry ID is returned in the dataSources object under "geometry" and "id".
        }
} 

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

Дополнительные сведения см. в следующих статьях:To learn more, please see: