Справочник по API Bing Local Business Search версии 7
Предупреждение
30 октября 2020 г. API-интерфейсы Поиск Bing перемещены из служб ИИ Azure в службы Поиск Bing. Эта документация приводится только для справки. Обновленную информацию см. в документации по API Поиска Bing. Инструкции по созданию ресурсов Azure для Поиска Bing приведены в статье Создание ресурса для Поиска Bing с помощью Azure Marketplace.
API Bing Local Business Search отправляет поисковый запрос Bing, чтобы получить результаты, которые включают рестораны, отели или других местные бизнесы. При поиске мест запрос может указывать имя местного бизнеса или категории (например, ближайших ресторанов). В результатах поиска сущностей содержатся субъекты, места или вещи. Местами в данном контексте являются предприятия, штаты, страны/регионы и т. д.
В следующих разделах приведены технические сведения об объектах ответа, параметрах и заголовках запроса, которые влияют на результаты поиска. См. в статьях Quickstart: Send a query to the Bing Local Business Search API in C# (Краткое руководство. Отправить запрос API Bing Local Business Search на языке C#) или Quickstart: Send a query to the Bing Local Business Search API using Java(Краткое руководство. Отправить запрос API Bing Local Business Search на языке Java) примеры того, как выполнять запросы.
Сведения о заголовках, которые должны включать запросы, см. в разделе Заголовки.
См. дополнительные сведения параметрах запросов.
См. дополнительные сведения об объектах JSON, которые содержит ответ.
Сведения о разрешенном использовании и отображении результатов см. в статье Project Answer Search use and display requirements (Использование и отображение требований к службе поиска ответов в проектах).
Конечная точка
Чтобы запросить результаты местного бизнеса, отправьте запрос GET.
https://api.cognitive.microsoft.com/bing/v7.0/localbusinesses/search
Для отправки запроса следует использовать протокол HTTPS.
Примечание
Максимальный размер URL-адреса составляет 2,048 символов. Чтобы длина вашего URL-адреса не превышала ограничение, максимальная длина ваших параметров запроса должна быть менее 1500 символов. Если длина URL-адреса превышает 2048 символов, сервер возвращает ошибку 404 (страница не найдена).
Заголовки
Ниже приведены заголовки, которые могут включать запрос и ответ.
Header | Описание |
---|---|
Принять | Дополнительный заголовок запроса. Тип мультимедиа по умолчанию — это приложение или JSON. Чтобы указать, что в ответе используется JSON-LD, задайте для заголовка Accept приложение или JSON+LD в качестве значения. |
Accept-Language | Дополнительный заголовок запроса. Список разделенных запятыми языков, используемых для строк пользовательского интерфейса. В этом списке языки указаны в порядке убывания по приоритету. Дополнительные сведения, включая ожидаемый формат, см. в этой статье. Этот заголовок и параметр запроса setLang являются взаимоисключающими. Не указывайте оба. Если задать этот заголовок, также необходимо указать параметр запроса cc. Чтобы определить рынок для возврата результатов, Bing использует первый поддерживаемый язык, который он находит в списке, и объединяет его со значением параметра cc . Если в список не включен поддерживаемый язык, Bing находит ближайший язык и рынок, который поддерживает запрос, или использует вычисление или рынок по умолчанию для результатов. Чтобы определить рынок, используемый Bing, см. заголовок BingAPIs-Market.Используйте этот заголовок и параметр запроса cc , только если указывается несколько языков. В противном случае используйте параметры запроса mkt и setLang.Строка пользовательского интерфейса — это строка, которая используется как метка в пользовательском интерфейсе. Есть несколько строк пользовательского интерфейса в объектах ответа JSON. Все ссылки на свойства Bing.com в объектах ответа применяют указанный язык. |
BingAPIs-Market | Заголовок ответа. Рынок, используемый для запроса. Формат значения — <код_языка>-<код_страны>. Например, en-US. |
BingAPIs-TraceId | Заголовок ответа. Идентификатор записи журнала, содержащей сведения о запросе. В случае ошибки запишите этот код. Если вы не можете определить и устранить проблему, укажите этот идентификатор вместе с другой информацией в запросе к группе поддержки. |
Ocp-Apim-Subscription-Key | Обязательный заголовок запроса. Ключ подписки, полученный при регистрации этой службы в службах ИИ Azure. |
Pragma | Дополнительный заголовок запроса. По умолчанию Bing возвращает кэшированное содержимое, если оно доступно. Чтобы Bing не возвращал кэшированное содержимое, установите для заголовка Pragma значение no-cache (например, Pragma:no-cache). |
User-Agent | Дополнительный заголовок запроса. Агент пользователя, отправивший запрос. Bing использует агент пользователя, чтобы обеспечить оптимизированное взаимодействие для мобильных пользователей. Приведенный ниже заголовок является необязательным, но его также рекомендуется указать. Заголовок User-Agent должен содержать ту же строку, которую отправляет любой широко используемый браузер. Дополнительные сведения об агентах пользователя см. в этой статье. Ниже приведены примеры использования строк user-agent.
|
X-MSEdge-ClientID | Дополнительный заголовок запроса и ответа. Bing использует этот заголовок для обеспечения согласованного поведения при выполнении разных вызовов Bing API. Bing часто проверяет новые функции и улучшения и использует идентификатор клиента в качестве ключа для назначения тестируемых возможностей. Если вы не используете один и тот же идентификатор клиента для нескольких запросов, Bing может назначить одному пользователю несколько конфликтующих функций. Назначение таких проверяемых возможностей может привести к несогласованному взаимодействию с пользователем. Например, если для второго запроса будет назначена другая проверяемая возможность, результат будет неожиданным для пользователя. Кроме того, Bing может использовать идентификатор клиента, чтобы адаптировать результаты веб-поиска к истории поиска этого идентификатора, обеспечивая более широкие возможности взаимодействия с пользователем. Bing также использует этот заголовок, чтобы повысить рейтинг результатов путем анализа активности, создаваемой идентификатором клиента. Повышение релевантности помогает улучшить качество результатов, предоставляемых API Bing, что, в свою очередь, обеспечивает более быстрые переходы по ссылкам для потребителей API. ВАЖНО! Считайте этот заголовок обязательным, хоть это и не так. Сохранение идентификатора клиента по нескольким запросам для одной и той же комбинации пользователя и устройства позволяет 1) потребителю API получать согласованный пользовательский интерфейс и 2) больше переходов по ссылкам благодаря лучшему качеству результатов от Bing API. Ниже приведены базовые правила использования, применяемые к этому заголовку.
Примечание. Ответы Bing могут как включать, так и не включать этот заголовок. Если ответ включает этот заголовок, сохраните идентификатор клиента и используйте его для всех последующих запросов Bing для пользователя на этом устройстве. Примечание. Если в запрос включен заголовок X-MSEdge-ClientID, этот запрос не должен содержать файлы cookie. |
X-MSEdge-ClientIP | Дополнительный заголовок запроса. IPv4-адрес или IPv6-адрес клиентского устройства. IP-адрес используется для обнаружения расположения пользователя. Bing использует сведения о расположении для выбора безопасного поведения поиска. ПРИМЕЧАНИЕ. Приведенный ниже заголовок является необязательным, однако всегда рекомендуется указывать его и заголовок X-Search-Location. Не маскируйте адрес (например, изменив последний октет на 0). Маскировка адреса приводит к тому, что определяется расположение, отдаленное от фактического расположения устройства. В результате Bing может выводить ошибочные результаты. |
X-Search-Location | Дополнительный заголовок запроса. Список пар "ключ — значение", разделенных точкой с запятой, которые описывают географическое расположение клиента. Bing использует сведения о расположении для определения поведения при безопасном поиске и возвращения релевантного локального содержимого. Укажите пару "ключ-значение" в формате <ключ>:<значение>. Ниже приведены ключи, которые можно использовать для определения расположения пользователя.
ПРИМЕЧАНИЕ. Рекомендуется всегда указывать географическое расположение пользователя. Это особенно важно, если IP-адрес клиента не точно отражает физическое расположение пользователя (например, если клиент использует VPN). Для получения оптимальных результатов следует включать этот заголовок и заголовок X-MSEdge-ClientIP. Как минимум, следует включать этот заголовок. |
Примечание
Помните, что условия использования требуют соблюдения всех применимых законов, в том числе в отношении использования этих заголовков. Например, в некоторых юрисдикциях, например европейской, есть требования на получение согласия пользователя перед размещением определенных устройств отслеживания на пользовательских устройствах.
Параметры запроса
Запрос может включать следующие параметры запроса. В столбце "Обязательно" отмечены обязательные параметры. К параметрам запроса нужно применить кодировку URL.
Имя | Значение | Тип | Обязательно |
---|---|---|---|
count | Количество результатов для возврата, начиная с индекса, указанного в параметре offset . |
Строка | Нет |
localCategories | Список параметров, которые определяют поиск по категории бизнеса. См. Search categories for the Bing Local Business Search API (Поиск категорий для API Bing Local Business Search) | Строка | Нет |
mkt | Рынок, по которому возвращаются результаты. Список возможных значений рынка приведен в разделе "Коды рынка". ПРИМЕЧАНИЕ. API Local Business Search в настоящее время поддерживает только рынок и язык en-us. |
Строка | Да |
offset | Индекс для запуска результатов, заданных параметром count . |
Целое число | Нет |
q | Термин поиска пользователя. | Строка | Нет |
responseFormat | Тип мультимедиа, используемый для ответа. Ниже приведены возможные значения, в которых не учитывается регистр.
По умолчанию используется JSON. Сведения об объектах JSON, которые содержат ответ, см. в разделе Объекты ответа. При указании JsonLd текст ответа включает объекты JSON-LD, содержащие результаты поиска. Сведения о JSON-LD см. на этом сайте. |
Строка | Нет |
safeSearch | Фильтр, используемый для фильтрации содержимого для взрослых. Ниже приведены возможные значения фильтра, в которых не учитывается регистр.
По умолчанию используется значение Moderate. ПРИМЕЧАНИЕ. Если запрос поступает с рынка, для которого политика для взрослых Bing требует параметра safeSearch со значением Strict, Bing игнорирует значение safeSearch и использует Strict.ПРИМЕЧАНИЕ. Если вы используете оператор запроса site: , в зависимости от запроса есть вероятность, что ответ включает содержимое для взрослых независимо от значения параметра запроса safeSearch . Используйте site: , только если вам известно о содержимом на сайте и ваш сценарий поддерживает возможность использования содержимого для взрослых. |
Строка | Нет |
setLang | Язык, используемый для строк пользовательского интерфейса. Укажите язык, используя двухбуквенный код ISO 639-1. Например, код для английского языка — EN. Он также является кодом по умолчанию. Хотя это необязательно, всегда следует указывать язык. Обычно для setLang задается язык, указанный в параметре mkt , если только пользователь не хочет, чтобы строки пользовательского интерфейса отображались на другом языке.Этот параметр и заголовок Accept-Language являются взаимоисключающими. Не указывайте оба. Строка пользовательского интерфейса — это строка, которая используется как метка в пользовательском интерфейсе. Есть несколько строк пользовательского интерфейса в объектах ответа JSON. Кроме того, все ссылки на свойства Bing.com в объектах ответа применяют указанный язык. |
Строка | Нет |
Объекты ответа
Ниже приведены объекты ответа JSON, которые ответ может включать. Если запрос выполняется успешно, объектом верхнего уровня в ответе будет SearchResponse. Если запрос завершается с ошибкой, то объектом верхнего уровня будет являться ErrorResponse.
Объект | Описание |
---|---|
Place | Определяет сведения о местных бизнесах, например, ресторан или гостиница. |
Ошибка
Определяет возникшую ошибку.
Элемент | Описание | Тип |
---|---|---|
code | Код ошибки, определяющий ее категорию. Список возможных кодов см. в разделе Коды ошибок. | Строка |
message | Текстовое описание ошибки. | Строка |
moreDetails | Подробное описание, которое предоставляет дополнительную информацию об ошибке. | Строка |
parameter | Параметр запроса, который вызвал эту ошибку. | Строка |
subCode | Код ошибки, по которому определяется ошибка. Например, если code имеет значение InvalidRequest, то subCode может иметь значение ParameterInvalid или ParameterInvalidValue. |
Строка |
value | Недопустимое значение параметра запроса. | Строка |
ErrorResponse
Объект верхнего уровня, который включается ответ при сбое обработки запроса.
Имя | Значение | Тип |
---|---|---|
_type | Указание типа. | Строка |
errors | Список ошибок, описывающих причины сбоя запроса. | Error[] |
Лицензия
Определяет лицензию, в рамках которой можно использовать текст или фотографию.
Имя | Значение | Тип |
---|---|---|
name | Имя лицензии. | Строка |
url | URL-адрес веб-сайта, где пользователь может получить дополнительные сведения о лицензии. Используйте имя и URL-адрес для создания гиперссылки. |
Строка |
Ссылка
Определяет компоненты гиперссылки.
Имя | Значение | Тип |
---|---|---|
_type | Указание типа. | Строка |
text | Отображаемый текст. | Строка |
url | URL-адрес. Используйте URL-адрес и отображаемый текст для создания гиперссылки. | Строка |
План
Определяет издателя.
Обратите внимание, что издатель может предоставить свое имя или веб-сайт, или и то, и другое.
Имя | Значение | Тип |
---|---|---|
name | Имя издателя. | Строка |
url | URL-адрес для веб-сайта издателя. Обратите внимание, что издатель может не предоставить веб-сайт. |
Строка |
Место
Определяет сведения о местных бизнесах, например, ресторан или гостиница.
Имя | Значение | Тип |
---|---|---|
_type | Тип указания, которому может быть присвоено одно из следующих имен:
|
Строка |
address | Почтовый адрес расположения сущности. | PostalAddress |
entityPresentationInfo | Дополнительные сведения о сущности, например указание, которое используется для определения типа сущности. Например, ресторан или гостиница. Полю entityScenario присваивается ListItem. |
EntityPresentationInfo |
name | Имя сущности. | Строка |
telephone | Номер телефона сущности. | Строка |
url | URL-адрес для веб-сайта сущности. Используйте этот URL-адрес вместе с именем сущности, чтобы создать гиперссылку, которая при щелчке направляет пользователя на веб-сайт сущности. |
Строка |
webSearchUrl | URL-адрес для результатов поиска Bing этого места. | Строка |
QueryContext
Определяет содержимое запроса, который Bing использует для запроса.
Элемент | Описание | Тип |
---|---|---|
adultIntent | Логическое значение, указывающее, есть ли в указанном запросе содержимое для взрослых. Значение равно true, если запрос имеет запрос на содержимое для взрослых, в противном случае — false. | Логическое |
alterationOverrideQuery | Строка запроса для принудительного использования исходной строки в Bing. Например, если строка запроса saling downwind, строка запроса переопределения будет +saling downwind. Помните, что необходимо закодировать строку запроса, в результате чего будет получена строка %2Bsaling+downwind. Это поле включается, только если исходная строка запроса содержит орфографическую ошибку. |
Строка |
alteredQuery | Строка запроса, используемая для выполнения запроса Bing. Bing использует измененную строку запроса, если исходная строка запроса содержит орфографические ошибки. Например, если строка запроса — saling downwind , измененная строка запроса будет sailing downwind .Это поле включается, только если исходная строка запроса содержит орфографическую ошибку. |
Строка |
askUserForLocation | Логическое значение, указывающее, требуется ли Bing расположение пользователя для получения точных результатов. При указании расположения пользователя с помощью заголовков X-MSEdge-ClientIP и X-Search-Location это поле можно игнорировать. Для запросов с учетом расположения, таких как "сегодняшняя погода" или "рестораны рядом со мной", которым требуется расположение пользователя для получения точных результатов, это поле имеет значение true. Для запросов с учетом расположения, которые включают расположение (например, "погода в Сиэтле"), это поле имеет значение false. Для этого поля также установлено значение false для запросов, которые не относятся к расположению, например "бестселлеры". |
Логическое |
originalQuery | Строка запроса, как указано в запросе. | Строка |
Identifiable
Имя | Значение | Тип |
---|---|---|
идентификатор | Идентификатор ресурса | Строка |
RankingGroup
Определяет группу результатов поиска, такие как основное поле.
Имя | Значение | Тип |
---|---|---|
items | Список результатов поиска для отображения в группе. | RankingItem |
RankingItem
Определяет элемент в результатах поиска для отображения.
Имя | Значение | Тип |
---|---|---|
resultIndex | Отсчитываемый от нуля индекс элемента в ответе для отображения. Если в элементе нет этого поля, в ответе могут отобразиться все элементы. Например, можно отобразить все статьи в ответе "Новости". | Целочисленный тип |
answerType | Ответ, содержащий элемент, который необходимо отобразить. Например, "Новости". Используйте этот тип, чтобы найти ответ в объекте SearchResponse. Тип — это имя поля SearchResponse. Тем не менее используйте тип ответа, только если этот объект включает поле значения; в противном случае игнорируйте его. |
Строка |
textualIndex | Индекс ответов в textualAnswers для отображения. | Целое число без знака |
value | Идентификатор, который определяет либо ответ для отображения, либо элемент ответа для отображения. Если идентификатор определяет ответ, покажите все элементы ответов. | Identifiable |
RankingResponse
Определяет, где должно быть размещено содержимое на странице результатов поиска и в каком порядке.
SearchResponse
Определяет объект верхнего уровня, который включает ответ при удачном запросе.
Обратите внимание, что если служба подозревает, что совершается атака типа "отказ в обслуживании", запрос будет успешно завершен (код состояния HTTP: 200 OК). Однако текст ответа будет пустым.
Имя | Значение | Тип |
---|---|---|
_type | Указание типа, которому задано значение SearchResponse. | Строка |
Места | Список сущностей, которые относятся к поисковому запросу. | Объект JSON |
queryContext | Объект, содержащий строку запроса, которую использует Bing. Этот объект содержит строку запроса, введенную пользователем. Он также может содержать измененную строку запроса, которую использует Bing в том случае, если строка запроса содержит орфографические ошибки. |
QueryContext |
Коды ошибок
Ниже приведены возможные коды состояния HTTP, которые возвращает запрос.
Код состояния | Описание |
---|---|
200 | Успешно. |
400 | Один из параметров запроса отсутствует или является недопустимым. |
401 | Ключ подписки отсутствует или является недопустимым. |
403 | Пользователь прошел проверку подлинности (например, с допустимым ключом подписки), но не имеет разрешений для обращения к запрошенному ресурсу. Bing также может вернуть это состояние, если для вызывающего объекта превышены месячные квоты. |
410 | В запросе использовался протокол HTTP вместо HTTPS. HTTPS является единственным поддерживаемым протоколом. |
429 | Вызывающий превысил свою квоту на число запросов в секунду. |
500 | Непредвиденная ошибка сервера. |
Если запрос завершается с ошибкой, ответ будет содержать объект ErrorResponse, который содержит список объектов Error, описывающих причину ошибки. Если ошибка связана с параметром, поле parameter
идентифицирует параметр, который является причиной проблемы. Если ошибка связана со значением параметра, поле value
идентифицирует недопустимое значение.
{
"_type": "ErrorResponse",
"errors": [
{
"code": "InvalidRequest",
"subCode": "ParameterMissing",
"message": "Required parameter is missing.",
"parameter": "q"
}
]
}
{
"_type": "ErrorResponse",
"errors": [
{
"code": "InvalidAuthorization",
"subCode": "AuthorizationMissing",
"message": "Authorization is required.",
"moreDetails": "Subscription key is not recognized."
}
]
}
Ниже приведены возможные коды ошибок и кодовые значения вложенных ошибок.
Код | SubCode (дополнительный код) | Описание |
---|---|---|
ServerError | UnexpectedError ResourceError NotImplemented |
Код состояния HTTP — 500. |
InvalidRequest | ParameterMissing ParameterInvalidValue HttpNotAllowed Блокировано |
Bing возвращает ошибку InvalidRequest (недопустимый запрос) всякий раз, когда любая часть запроса недопустима. Например, отсутствует обязательный параметр или значение параметра недопустимо. В случае ошибки ParameterMissing или ParameterInvalidValue возвращается код состояния HTTP 400. Если вместо HTTPS используется протокол HTTP, Bing возвращает HttpNotAllowed и код состояния HTTP 410. |
RateLimitExceeded | Дополнительные коды не используются | Bing возвращает ошибку RateLimitExceeded всякий раз при превышении квоты запросов в секунду (QPS) или запросов в месяц (QPM). При превышении QPS Bing возвращает код состояния HTTP 429, а если превысить QPM, Bing вернет код 403. |
InvalidAuthorization | AuthorizationMissing AuthorizationRedundancy |
Bing возвращает InvalidAuthorization, когда Bing не может проверить подлинность вызывающего объекта. Например, когда заголовок Ocp-Apim-Subscription-Key отсутствует или при недопустимом ключе подписки.Избыточность возникает, если указать более одного способа проверки подлинности. При ошибке InvalidAuthorization кодом состояния HTTP будет 401. |
InsufficientAuthorization | AuthorizationDisabled AuthorizationExpired |
Bing возвращает InsufficientAuthorization, когда вызывающая сторона не имеет разрешений на доступ к ресурсу. Это может произойти, если ключ подписки отключен или срок его действия истек. При ошибке InsufficientAuthorization возвращается код состояния HTTP 403. |
Дальнейшие действия
- Quickstart: Send a query to the Bing Local Business Search API in C# (Краткое руководство. Отправка запроса в API Bing Local Business Search с помощью C#)
- Краткое руководство. Отправка запроса в API Bing для поиска местных компаний с помощью Java
- Краткое руководство. Использование Local Business Search с помощью Node
- Краткое руководство. Отправка запроса в API Bing Local Business Search с помощью Python