Наилучшие практики для службы Azure Maps Search

служба поиска Azure Maps включает API- интерфейсы, которые предоставляют различные возможности, помогающие разработчикам искать адреса, места, бизнес-описания по имени или категории и другие географические сведения. Например, поиск нечеткий позволяет пользователям искать адрес или точку интереса (POI).

В этой статье объясняется, как применять рекомендации при вызове данных из службы поиска Azure Maps. Узнайте, как:

  • Создавать запросы, чтобы получать наиболее релевантные результаты
  • Сужение результатов поиска
  • Общие сведения о различиях между типами результатов
  • Читать структуру ответа на запрос поиска адресов

Требуемые условия

Вы можете использовать любую среду разработки API, например Бруно, для запуска примеров HTTP-запросов, показанных в этой статье, или для создания вызовов REST.

Рекомендации по геокодированию адресов

При поиске полного или частичного адреса с помощью служба Azure Maps API считывает ключевые слова из поискового запроса. После этого он возвращает координаты долготы и широты нужного адреса. Этот процесс называется геокодированием.

Возможность геокодирования в стране или регионе зависит от доступности дорожных данных и точности службы геокодирования. Дополнительные сведения о возможностях геокодирования Azure Maps по странам или регионам см. в разделе "Покрытие геокодирования".

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

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

Примечание.

API поиска поддерживают больше параметров, чем описано в этой статье.

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

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

  • Задайте параметр countrySet. Например, установите для него значение US,FR. По умолчанию API выполняет поиск по всему миру, поэтому он может давать нерелевантные результаты. Если запрос не содержит параметр countrySet, поиск может возвращать неточные результаты. Например, при поиске города с именем Бельвью(Bellevue) возвращаются результаты для США и Франции, так как в обеих этих странах есть город с именем Бельвью.

  • Используйте параметры topleft и btmRight, чтобы задать ограничивающий прямоугольник. Эти параметры ограничивают поиск определенной областью на карте.

  • Чтобы влиять на область релевантности результатов, определите параметры координат — lat и lon. Чтобы задать радиус области поиска, используйте параметр radius.

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

Используйте Search Fuzzy, если не знаете, что именно пользователь введёт в поисковый запрос. Например, пользователь может ввести адрес или тип точки интереса (POI), например "торговый центр". API-интерфейс объединяет поиск точек интереса и геокодирование в канонический однострочный поиск:

  • Параметры minFuzzyLevel и maxFuzzyLevel позволяют выдавать релевантные результаты даже в том случае, если параметры запроса не точно соответствуют необходимой пользователю информации. Чтобы повысить качество поиска и сократить число нерелевантных результатов, задайте для поисковых запросов значения по умолчанию — minFuzzyLevel=1 и maxFuzzyLevel=2.

    Например, если для параметра maxFuzzyLevel задано значение 2, поисковый запрос рестран будет соответствовать слову ресторан. При необходимости можно изменить уровни нечеткости, используемые по умолчанию.

  • Используйте параметр idxSet, чтобы задать приоритет для точного набора типов результатов. Чтобы определить приоритет точного набора результатов, отправьте разделенный запятыми список индексов. Порядок элементов в списке не имеет значения. Azure Maps поддерживает следующие индексы.

  • Addr - Диапазоны адресов: точки адресов, определяемые интерполяцией от начала до конца улицы. Эти точки представляются в виде диапазонов адресов.

  • Geo - Географии: административные подразделения земли. Географическим регионом, например, может быть страна, регион, штат или город.

  • PAD - Адреса точек: адреса, содержащие имя и номер улицы. Точечные адреса могут находиться в индексе. Например, Soquel Dr 2501. Точечный адрес обеспечивает самый высокий уровень точности доступный для адресов.

  • POI - Точки интереса: точки на карте, которые считаются достойными внимания или которые могут быть интересными. Адрес поиска не возвращает POIS.

  • Str - Улицы: улицы на карте.

  • XStr - Перекрестки: узлы или места, где пересекаются две улицы.

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

  • idxSet=POI — искать только точки интереса.

  • idxSet=PAD,Addr — поиск только адресов. PAD указывает точечный адрес, Addr указывает диапазон адресов.

Обратное геокодирование и фильтрация по типу географической сущности

При обратном геокодировании с помощью Search Address Reverse сервис может возвращать многоугольники для административных областей. Например, может потребоваться получить полигональный контур для города. Чтобы сузить область поиска до конкретных типов сущности географических регионов, включите в запрос параметр entityType.

Полученный ответ будет содержать идентификатор географического региона и соответствующий тип сущности. Если вы предоставляете несколько сущностей, конечная точка возвращает наименьшую доступную сущность. Полученный геометрический идентификатор можно использовать для получения геометрического вида географического региона через службу Search Polygon.

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

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

Ответ

{
    "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"
        }
    ]
}

Установите язык результатов

Чтобы задать язык выдаваемых результатов поиска, используйте параметр language. Если запрос не задает язык, служба поиска использует наиболее распространенный язык в стране или регионе по умолчанию. Если данные на указанном языке не доступны, используется язык по умолчанию.

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

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

Чтобы найти дополнительные результаты для частичных запросов, задайте для параметра typeahead значение true. Такой запрос будет интерпретироваться как запрос с частичными входными данными, а поиск перейдет в режим прогнозирования. Если для параметра typeahead не установлено значение true, служба предполагает, что вся соответствующая информация была передана.

В следующем примере запроса служба "Адрес поиска" запрашивается для Корпорации Майкрософт. typeahead Здесь для параметра задано значение true. Ответ показывает, что служба поиска интерпретировала этот запрос как частичный. Ответ содержит результаты для автоматически предположенного запроса.

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

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

Ответ

{
    "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-кода для работы со специальными символами

Чтобы найти адреса на пересечении улиц, закодируйте URI, чтобы корректно обработать специальные символы в адресе. Рассмотрим этот пример адреса: 1-й авеню и Union Street, Сиэтл. В данном случае перед отправкой запроса необходимо закодировать символ амперсанда (&).

Кодирование символьных данных в URI. В URI кодируйте все символы с помощью знака процента (%) и шестнадцатеричного значения двух символов, соответствующего коду UTF-8 символов.

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

Начнем с этого адреса:

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

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

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

Используйте следующие методы.

JavaScript или TypeScript:

encodeURIComponent(query)

C# или Visual Basic:

Uri.EscapeDataString(query)

Java:

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

Python:

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

C++:

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

PHP.

urlencode(query)

Ruby.

CGI::escape(query)

Swift:

query.stringByAddingPercentEncodingWithAllowedCharacters(.URLHostAllowedCharacterSet())

Вперёд:

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

Рекомендации по поиску точек интереса

При поиске точек интереса можно запрашивать результаты по названию. Например, можно искать компанию по ее названию.

countrySet Используйте параметр, чтобы указать страны или регионы, в которых приложение нуждается в охвате. По умолчанию поиск ведется по всему миру. Это слишком широкий поиск, и он может дать ненужные результаты, а также занять много времени.

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

При отправке запроса можно указать разделенный запятыми список торговых марок. Используйте этот список, чтобы сузить результаты до набора конкретных торговых марок путем задания параметра brandSet. Порядок элементов в списке не имеет значения. Когда вы указываете несколько списков торговых марок, возвращаемые результаты должны соответствовать по крайней мере одному из ваших списков.

Чтобы изучить поиск фирменной символики, сделайте запрос на поиск по категориям POI . В следующем примере вы ищете заправочные станции возле кампуса Microsoft в Редмонде, Штат Вашингтон. В ответе содержатся сведения о торговой марке для каждой найденной точки интереса.

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

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

Ответ

{
    "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 поиска точек интереса вы можете искать аэропорты, используя их официальные коды. Например, для поиска международного аэропорта Сиэтл/Такома можно использовать код SEA:

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

Чтобы получить результаты POI по определенному расположению, используйте поиск поблизости. Конечная точка возвращает только результаты POI (точек интереса). Он не принимает параметр поискового запроса.

Задайте радиус, чтобы ограничить результаты.

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

Чтобы найти адрес в Сиэтле, выполните запрос поиска по адресу в службу поиска Azure Maps. В следующем URL-адресе запроса задайте для параметра countrySet значение US, чтобы выполнить поиск адреса в США.

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

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

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

  • Адрес точки: точки на карте с определенным адресом, содержащим название улицы и номер дома. Точечный адрес обеспечивает самый высокий уровень точности для адресов.

  • Диапазон адресов: диапазон точек адресов, интерполируемых с начала и конца улицы.

  • География: области на карте, представляющие административные подразделения земли, такие как страна или регион, штат или город.

  • POI: точки на карте, которые стоит внимания, и это может быть интересно.

  • Улица: улицы на карте. Адреса преобразуются в координаты широты и долготы улицы, на которой расположен этот адрес. Номер дома может не быть обработан.

  • Перекрестная улица: пересечения. Перекресток — это место, где пересекаются две улицы.

Ответ

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

  • Адрес точки
  • Улица
  • Перекресток

Обратите внимание, что поиск по адресу не дает результаты по точкам интереса.

Параметр Score для каждого объекта ответа указывает, как показатель соответствия соотносится с аналогичными показателями других объектов в том же ответе. Дополнительные сведения о параметрах объекта ответа см. в разделе Получение 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
                }
            }
        }
    ]
}

Геометрия

Тип отклика Geometry может включать идентификатор геометрии, возвращаемый в объекте под dataSources, geometry и id. Например, вы можете использовать службу Search Polygon для запроса геометрических данных в формате GeoJSON. С помощью этого формата можно получить контур города или аэропорта для нужного набора сущностей. Затем эти данные о границах можно использовать для настройки геозоны или поиска точек интереса в пределах заданного геометрического контура.

Ответы на запросы поиск по адресу или поиск по нечетким параметрам могут включать идентификатор геометрии, возвращенный в объекте dataSources в поле geometry и id:

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

Следующие шаги

Дополнительные сведения см. на следующих ресурсах:

Как сформировать запросы к службе поиска Azure Maps

Документация по API службы

Служба поиска Azure Maps предоставляет REST API интерфейсы для прямого геокодирования, обратного геокодирования, автозаполнения, пакетной обработки и извлечения административных границ. Начиная с API версии 2026-01-01, поиск организован вокруг операций с конкретной задачей, а не монолитных конечных точек поиска версии 1. В этой статье описываются основные понятия и рекомендации по созданию приложений с помощью последнего API поиска.

Требуемые условия

Вы можете использовать любую среду разработки API, например Бруно, для запуска примеров HTTP-запросов, показанных в этой статье, или для создания вызовов REST.

Основные понятия поиска

Операции с конкретными задачами

Каждая возможность поиска предоставляется через выделенный API, например Get Geocoding, Get Geocode Autocomplete, Get Reverse Geocoding или Get Polygon. Это разделение повышает четкость, производительность и выравнивание намерений.

Географические сигналы релевантности

Большинство API поиска принимают географические предвзятые входные данные, такие как координаты, ограничивающие прямоугольники или фильтры стран или регионов. Эти сигналы сильно влияют на ранжирование и качество результатов.

Пакетная обработка

API пакетной службы позволяют выполнять несколько запросов в одном запросе для крупномасштабных рабочих нагрузок.

Лучшие практики для прямого геокодирования

Используйте Получить геокодирование при преобразовании адреса или названия места в географические координаты.

Пример запроса на прямое геокодирование с использованием параметра query.

GET https://atlas.microsoft.com/geocode
  ?api-version=2026-01-01
  &query=140th%20Ave%20NE%2C%20Redmond
  &top=1
  &subscription-key={Your-Azure-Maps-Key}

Улучшение качества результатов для геокодирования на основе запросов

API получения геокодирования намеренно терпим к частичным и неполным адресам и незначительным опечаткам. Эта гибкость может создавать технически допустимые совпадения, которые не подходят для сценариев "отправить запрос в поиск", если пользователь ожидает точного совпадения или вовсе отсутствия результатов.

В этом разделе описаны практические методы снижения низкого качества совпадений для поиска путем объединения сигналов, возвращаемых геокодированием:

  • Достоверность (высокий, средний, низкий). Дополнительные сведения см. в разделе ConfidenceEnum.
  • Коды совпадений (Хороший, неоднозначный, UpHierarchy). Дополнительные сведения см. в разделе MatchCodesEnum.
  • Тип результата (properties.type например, Address, PopulatedPlace, RoadBlock, AdminDivision1). Дополнительные сведения см. в разделе properties.type.

Примечание.

RoadBlock официально указан как возможное значение properties.type и также ссылается в документации по match-code в качестве примера резервного UpHierarchy варианта. Воспринимайте это как сигнал того, что служба не смогла обработать запрос до более точного адреса на уровне улицы.

Предпочитайте структурированные параметры, если вы знаете компоненты адреса

Если приложение собирает адресные части (улица, город, почтовый индекс, страна или регион), используйте структурированные address параметры вместо одного параметра свободной формы query . Обычно это дает более точные результаты, чем поиск только по запросу.

Пример структурированного запроса (полный известный адрес)
GET https://atlas.microsoft.com/geocode
  ?api-version=2026-01-01
  &addressLine=1%20Microsoft%20Way
  &locality=Redmond
  &postalCode=98052
  &countryRegion=US
  &top=1
  &subscription-key={Your-Azure-Maps-Key}

Это важно

При использовании query параметра допустимы только подмножество параметров (например, bbox, location, view, top). Передача структурированных полей (например, локальности) наряду query может привести к ошибке конфликтующих параметров.

Добавить контекст местоположения к поисковым запросам, основанным на геопривязке

Когда вам необходимо использовать параметр query, добавьте географический контекст для направления результатов в ожидаемую область. Например, укажите ограничивающее поле (bbox) с помощью формата [lon1,lat1,lon2,lat2].

Пример запроса на основе запросов (сценарий клиента) с ограничивающим полем смещения
GET https://atlas.microsoft.com/geocode
  ?api-version=2026-01-01
  &query=1%20Microsoft%20Way
  &bbox=-122.35,47.45,-121.90,47.85
  &top=5
  &subscription-key={Your-Azure-Maps-Key}

Это снижает вероятность совпадений с низкой достоверности в несвязанных регионах, когда входные данные слабо структурированы.

Фильтрация с помощью достоверности и кодов совпадений + тип результата (рекомендуется)

Получение геокодирования возвращает несколько сигналов в функциях[].properties, включая confidence, matchCodesи type. Используйте их вместе, а не фильтрацию по confidence отдельности.

Почему уверенность в одиночку недостаточна

  • Средняя достоверность может указать допустимый результат, если запрос является неоднозначным, и недостаточно контекста для ранжирования одного кандидата по другому.

  • Средняя достоверность также может возникать, если служба возвращает менее точное совпадение, чем запрошено, и задает код UpHierarchy соответствия (например, сопоставление только почтового индекса при запросе адреса).

Переформулированное объяснение: как возникают результаты по принципу "up-hierarchy"

Если служба не может найти совпадение по определенности, подразумеваемой запросом, она может "переместиться вверх по географической иерархии" и вернуть более широкое расположение (например, город, административное подразделение или страна или регион). В этих случаях matchCodes включает UpHierarchy, а properties.type указывает, какой уровень был возвращен.

Практическое руководство по фильтрации (применяется в этом порядке)
  1. Отклоняйте низкокачественные совпадения для UX точного поиска Если confidence имеет значение "Низкий", рассматривайте результат как недопустимый для рабочего процесса точного соответствия.
  2. Обнаружение резервных уровней иерархии Если matchCodes включает UpHierarchy, служба не могла соответствовать запрошенной точности и вернула более широкое расположение. Используется type для определения того, какой уровень был возвращен (например, , PopulatedPlace, AdminDivision1CountryRegionили RoadBlock).
  3. Проверка ожидаемого типа результата Если в пользовательском интерфейсе ожидается соответствие на уровне улицы, примите результаты только в том случае, если тип достаточно конкретный (например, Адрес) и отклонять более широкие типы (например, PopulatedPlace). Это предотвращает использование резервного варианта города или штата, когда пользователь намерен указать конкретный адрес.
  4. Явная обработка неоднозначности Если matchCodes включает в себя Ambiguous, кандидаты могут оставаться допустимыми. Рассмотрите возможность возврата нескольких кандидатов или получения дополнительных сведений (почтовый индекс, город или ограниченная область поиска).

Подсказка

Используйте properties.type, чтобы понять, что было возвращено, и matchCodes, чтобы понять, как оно было получено (например, UpHierarchy резерв).

Использование геокодирования в качестве шага обогащения данных

Многие организации собирают данные о клиентах путём ввода данных в свободной форме, часто без валидации адресов. В результате эти наборы данных часто содержат адреса без доставки или низкого качества. Если вы геокодировали большие, неоцененные наборы адресов, некоторые записи возвращают слабые совпадения или нет результатов вообще. Это нормальное поведение и не указывает на сбой службы.

Наиболее вероятные причины:

  • Неверно написанные адреса или несогласованное форматирование адресов
  • Неполные адреса
  • Сведения об интерьере (например, номера квартиры, офиса или этажа), которые не являются частью полноправного адреса.

Обработка геокодирования как процесса обогащения данных, а не строгого шага проверки:

  • Отправка адресов для геокодирования.
  • Примите совпадения с высокой степенью достоверности и пометьте нерешённые или результаты с низкой степенью достоверности.
  • Повторно обработайте помеченные записи только после очистки или нормализации исходных данных.

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

Понимание пустых результатов геокодирования

Запрос геокодирования может возвращать ответ HTTP 200 (ОК) без результатов.

Это означает, что запрос был успешно обработан, но не найден соответствующий адрес или место. Она не представляет собой сбой службы.

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

Примечание.

Ограничения запросов Azure Maps, квоты и поведение регулирования настраиваются на уровне подписки Azure. Сведения о ценах, ограничениях использования и мониторинге см. в статье:

Рекомендации по автозаполнениям

Используйте Get Geocode Autocomplete для интерактивных сценариев ввода пользователей. Recommendations:

  • Активируйте запросы автозаполнения после ввода трех или более символов.
  • Всегда предоставлять либо coordinates, либо bbox.
  • Ограничьте результаты с помощью resultTypeGroups или resultTypes.

Пример запроса автозаполнения

GET https://atlas.microsoft.com/geocode:autocomplete
  ?api-version=2026-01-01
  &query=1%20Micro
  &coordinates=-122.129,47.639
  &subscription-key={Your-Azure-Maps-Key}

Рекомендации по обратному геокодированию

Используйте обратное геокодирование для преобразования координат в читаемый человеком адрес.

Recommendations:

  • Предпочитайте пакетное обратное геокодирование для телеметрии, отслеживания или других рабочих нагрузок с большим объемом.
  • Кэшируйте результаты и избегайте повторяющихся вызовов координат, которые не изменяются.
  • Проверьте порядок координат и точность, чтобы обеспечить точные и согласованные результаты.
  • Ожидайте приблизительные или частичные адреса в некоторых местах и обработайте эти случаи надлежащим образом.

Пример запроса на обратное геокодирование

GET https://atlas.microsoft.com/reverseGeocode
  ?api-version=2026-01-01
  &coordinates=-122.129,47.639
  &subscription-key={Your-Azure-Maps-Key}

Рекомендации по пакетным операциям

API пакетной службы повышают пропускную способность и сокращают нагрузку на сеть.

Когда следует использовать:

  • Импорт списков адресов
  • Фоновые задания обогащения
  • Крупномасштабная обработка данных

Пример запроса на пакетное геокодирование

POST https://atlas.microsoft.com/geocode:batch
  ?api-version=2026-01-01
  &subscription-key={Your-Azure-Maps-Key}

Включите следующие элементы в текст запроса:

{
  "batchItems": [
    { "query": "1 Microsoft Way, Redmond, WA" },
    { "query": "1600 Amphitheatre Parkway, Mountain View, CA" }
  ]
}

Дополнительные сведения см. в статье Get Geocoding Batch.

Получение примера запроса пакетного обратного геокодирования

POST https://atlas.microsoft.com/reverseGeocode:batch
  ?api-version=2026-01-01
  &subscription-key={Your-Azure-Maps-Key}

Включите следующие элементы в текст запроса:


{
  "batchItems": [
    { "coordinates": [-122.129, 47.639] },
    { "coordinates": [-122.084, 37.422] }
  ]
}

Дополнительные сведения см. в статье Получение обратного геокодирования пакетной службы.

Рекомендации по административным границам

Используйте Get Polygon для получения геометрии административной границы.

Recommendations:

  • Используйте этот метод только в том случае, если требуется геометрия границ.
  • Выберите геометрическое разрешение, соответствующее потребностям приложения. Используйте resolution=small для возврата более управляемого размера многоугольника и избегайте resolution=huge , если вы явно не требуете строго подробной геометрии, так как она может создавать очень большие ответы.

Пример запроса данных о административных границах

GET https://atlas.microsoft.com/polygon
  ?api-version=2026-01-01
  &entityId=US-WA
  &resolution=small
  &subscription-key={Your-Azure-Maps-Key}

Следующие шаги

Документация по API службы

Перенос API службы поиска Azure Maps 1.0

  • Last updated on