Справочник по Поиск изображений API версии 7
Поиск изображений API позволяет отправить поисковый запрос в Bing и вернуть список соответствующих изображений. В этом разделе содержатся технические сведения о параметрах запросов и заголовках, которые используются для запроса изображений и объектов ответа JSON, содержащих их. Примеры, демонстрирующие, как выполнять запросы, см. в разделе Поиск изображений в Интернете.
Сведения о заголовках, которые должны содержаться в запросах, см. в разделе заголовки запросов.
Сведения о параметрах запроса, которые должны быть включены в запросы, см. в разделе Параметры запроса.
Сведения об объектах ответа JSON, которые могут содержать ответы, см. в разделе объекты ответов.
Сведения о разрешенном использовании и отображении результатов см. в разделе Поиск Bing использования API и требования к отображению.
Так как формат и параметры URL-адресов могут измениться в любой момент без предварительного уведомления, используйте все URL-адреса как есть. Формат и параметры URL-адресов не следует учитывать, если это явно не обозначено.
Конечные точки
Чтобы запросить изображения, отправьте запрос GET на один из следующих URL-адресов:
| Конечная точка | Описание |
|---|---|
| https://api.cognitive.microsoft.com/bing/v7.0/images/search | Возвращает изображения, относящиеся к поисковому запросу пользователей. |
| https://api.cognitive.microsoft.com/bing/v7.0/images/details | Возвращает ценную информацию о изображении, например на веб-страницах, содержащих изображение. |
| https://api.cognitive.microsoft.com/bing/v7.0/images/trending | возвращает изображения, которые набирают популярность. За основу берутся результаты поисковых запросов, выполненных другими пользователями. Изображения разбиваются на разные категории. Например, Поиск популярных людей. Список рынков, для которых поддерживается поиск популярных изображений, см. в статье Получение изображений, набирающих популярность. |
Для подписок с несколькими службами необходимо включить регион в URL-адрес. Например: westus.api.cognitive.microsoft.com. См. раздел Поддерживаемые регионы.
Для отправки запроса следует использовать протокол HTTPS.
Максимальный размер URL-адреса составляет 2,048 символов. Чтобы длина вашего URL-адреса не превышала ограничение, максимальная длина ваших параметров запроса должна быть менее 1500 символов. Если длина URL-адреса превышает 2048 символов, сервер возвращает ошибку 404 (страница не найдена).
Заголовки
Ниже приведены заголовки, которые могут включать запрос и ответ.
| Header | Описание |
|---|---|
| Принять | Дополнительный заголовок запроса. Тип мультимедиа по умолчанию — это приложение или JSON. Чтобы указать, что в ответе используется JSON-LD, задайте для заголовка Accept приложение или JSON+LD в качестве значения. |
| Accept-Language | Дополнительный заголовок запроса. Список разделенных запятыми языков, используемых для строк пользовательского интерфейса. В этом списке языки указаны в порядке убывания по приоритету. Дополнительные сведения, включая ожидаемый формат, см. в этой статье. Этот заголовок и параметр запроса setLang являются взаимоисключающими —, не указывайте оба. Строка пользовательского интерфейса — это строка, которая используется как метка в пользовательском интерфейсе. Есть несколько строк пользовательского интерфейса в объектах ответа JSON. Все ссылки на свойства Bing.com в объектах ответа применяют указанный язык. |
| BingAPIs-Market | Заголовок ответа. Идентификатор записи журнала, содержащей сведения о запросе. В случае ошибки запишите этот код. Если вы не можете определить и устранить проблему, укажите этот идентификатор вместе с другой информацией в запросе к группе поддержки. |
| Content-Type | Дополнительный заголовок запроса. Если для параметра запроса модулей задано значение рекогнизедентитиес, можно указать двоичный файл изображения в теле запроса POST. Если указать образ в тексте запроса POST, необходимо указать этот заголовок и присвоить ему значение multipart/form-data. Максимальный размер изображения — 1 МБ. |
| Ocp-Apim-Subscription-Key | Обязательный заголовок запроса. Ключ подписки, полученный при регистрации для использования этой службы в Cognitive Services. |
| Pragma | Дополнительный заголовок запроса. По умолчанию Bing возвращает кэшированное содержимое, если оно доступно. Чтобы предотвратить кэшированное содержимое, установите заголовок директивы pragma в значение No-cache (например, pragma: No-cache). |
| Повтор-после | Заголовок ответа. Ответ включает этот заголовок, если превышено допустимое количество запросов в секунду (QPS) или в месяц (КПМ). Заголовок содержит количество секунд, в течение которых необходимо ожидать перед отправкой другого запроса. |
| User-Agent | Дополнительный заголовок запроса. Агент пользователя, отправивший запрос. Bing использует агент пользователя, чтобы обеспечить оптимизированное взаимодействие для мобильных пользователей. Приведенный ниже заголовок является необязательным, но его также рекомендуется указать. Заголовок User-Agent должен содержать ту же строку, которую отправляет любой широко используемый браузер. Дополнительные сведения об агентах пользователя см. в этой статье. Bing использует этот заголовок для обеспечения согласованного поведения при выполнении разных вызовов Bing API. Bing часто проверяет новые функции и улучшения и использует идентификатор клиента в качестве ключа для назначения тестируемых возможностей. Если вы не используете один и тот же идентификатор клиента для нескольких запросов, Bing может назначить одному пользователю несколько конфликтующих функций. Назначение таких проверяемых возможностей может привести к несогласованному взаимодействию с пользователем. Например, если для второго запроса будет назначена другая проверяемая возможность, результат будет неожиданным для пользователя. Кроме того, Bing может использовать идентификатор клиента для адаптации результатов Интернета к журналу поиска идентификатора клиента, что обеспечивает более широкие возможности для пользователя. Bing также использует этот заголовок, чтобы повысить рейтинг результатов путем анализа активности, создаваемой идентификатором клиента. Повышение релевантности помогает улучшить качество результатов, предоставляемых API Bing, что, в свою очередь, обеспечивает более быстрые переходы по ссылкам для потребителей API. ВАЖНО! Считайте этот заголовок обязательным, хоть это и не так. Сохранение идентификатора клиента по нескольким запросам для одной и той же комбинации пользователя и устройства позволяет 1) потребителю API получать согласованный пользовательский интерфейс и 2) больше переходов по ссылкам благодаря лучшему качеству результатов от Bing API. Если этот заголовок не включается в запрос, Bing создает идентификатор и возвращает его в заголовке ответа X-MSEdge-ClientID. Этот заголовок не следует включать в запрос, только когда пользователь в первый раз использует приложение на этом устройстве. В следующий раз, когда пользователь будет использовать приложение на этом устройстве, извлеките сохраненный идентификатор клиента. Примечание. Ответы Bing могут как включать, так и не включать этот заголовок. Если ответ включает этот заголовок, сохраните идентификатор клиента и используйте его для всех последующих запросов Bing для пользователя на этом устройстве. Примечание. Если в запрос включен заголовок X-MSEdge-ClientID, этот запрос не должен содержать файлы cookie. |
| X-MSEdge-ClientIP | Дополнительный заголовок запроса. IPv4-адрес или IPv6-адрес клиентского устройства. IP-адрес используется для обнаружения расположения пользователя. Bing использует сведения о расположении для выбора безопасного поведения поиска. ПРИМЕЧАНИЕ. Приведенный ниже заголовок является необязательным, однако всегда рекомендуется указывать его и заголовок X-Search-Location. Не маскируйте адрес (например, изменив последний октет на 0). Маскировка адреса приводит к тому, что определяется расположение, отдаленное от фактического расположения устройства. В результате Bing может выводить ошибочные результаты. |
| X-Search-Location | Дополнительный заголовок запроса. Примечание. Хотя многие из этих ключей не являются обязательными, чем больше информации вы предоставите, тем точнее будут результаты поиска. Примечание. Хотя это необязательно, рекомендуется всегда указывать географическое расположение пользователя. Это особенно важно, если IP-адрес клиента не точно отражает физическое расположение пользователя (например, если клиент использует VPN). Для достижения оптимальных результатов необходимо включить этот заголовок и заголовок X-Search-ClientIP, но как минимум следует включить этот заголовок. |
Помните, что условия использования требуют соблюдения всех применимых законов, в том числе в отношении использования этих заголовков. Например, в некоторых юрисдикциях, например европейской, есть требования на получение согласия пользователя перед размещением определенных устройств отслеживания на пользовательских устройствах.
Параметры запроса
Ниже приведены параметры запроса, которые может содержать запрос. В столбце «Обязательно» отмечены обязательные параметры. Значения параметров запроса необходимо включить в URL-адрес. Сведения о параметрах запроса, используемых для фильтрации изображений, возвращаемых Bing, см. в разделе Фильтрация параметров запроса.
| Имя | Значение | Тип | Обязательно |
|---|---|---|---|
| cab | Нижняя координата области для обрезки. Координата представляет собой дробное значение высоты исходного изображения и измеряется от верхнего левого угла изображения. Укажите координату в виде значения от 0,0 до 1,0. Используйте этот параметр только с API Insights. Не указывайте этот параметр при вызове образов, обучении изображений или Поиск в Интернете интерфейсах API. | Float | Нет |
| Cal | Левая координата области для обрезки. Координата представляет собой часть ширины исходного изображения и измеряется от верхнего левого угла изображения. Укажите координату в виде значения от 0,0 до 1,0. Используйте этот параметр только с API Insights. Не указывайте этот параметр при вызове образов, обучении изображений или Поиск в Интернете интерфейсах API. | Float | Нет |
| автомобиле | Правая координата области для обрезки. Координата представляет собой часть ширины исходного изображения и измеряется от верхнего левого угла изображения. Укажите координату в виде значения от 0,0 до 1,0. Используйте этот параметр только с API Insights. Не указывайте этот параметр при вызове образов, обучении изображений или Поиск в Интернете интерфейсах API. | Float | Нет |
| Кот | Верхняя координата области для обрезки. Координата — это часть высоты исходного изображения, которая измеряется от верхнего левого угла изображения. Укажите координату в виде значения от 0,0 до 1,0. Если задать этот параметр, также необходимо указать заголовок Accept-Language. Bing использует первый поддерживаемый язык, находящийся на указанных языках, и объединяет его с кодом страны для определения рынка, для которого возвращаются результаты. Если в список не включен поддерживаемый язык, Bing находит ближайший язык и рынок, поддерживаемые для запроса. Или же Bing может использовать агрегированный или используемый по умолчанию рыночный результат. Используйте этот параметр запроса и Accept-Language заголовок, только если задано несколько языков. В противном случае следует использовать mkt setLang Параметры запроса и. Этот параметр и параметр запроса mkt— являются взаимоисключающими. Не указывайте оба. | Строка | Нет |
| count | Число образов, возвращаемых в ответе. Фактическое число полученных результатов может быть меньше запрошенного. Значение по умолчанию — 35. Максимальное значение — 150. Этот параметр используется вместе с offset параметром для результатов страницы. Например, если пользовательский интерфейс отображает 20 изображений на странице, установите значение count 20 и значение offset 0, чтобы получить первую страницу результатов. Для каждой последующей страницы увеличивается offset на 20 (например, 0, 20, 40). Максимальный поддерживаемый размер изображения составляет 1 МБ. Примечание. Если это известно, рекомендуется всегда указывать на рынке. Таким образом Bing может направить запрос и вернуть соответствующий и оптимальный ответ. Если вы укажете рыночный, не указанный в кодах рынка, Bing использует наиболее подходящий код рынка на основе внутреннего сопоставления, которое может быть изменено. Примечание. Этот модуль нельзя использовать с любым другим модулем. Если указать его в других модулях, ответ не будет содержать распознаваемые сущности. Чтобы включить связанные поиски, запрос должен содержать исходную строку запроса. Хотя исходная строка запроса не является обязательной для похожих изображений или продуктов, ее следует всегда включать, так как она может помочь улучшить релевантность и результаты. Для результатов страницы используйте этот параметр вместе с count параметром. Например, если пользовательский интерфейс отображает 20 изображений на странице, установите значение count 20 и значение offset 0, чтобы получить первую страницу результатов. Для каждой последующей страницы увеличивается offset на 20 (например, 0, 20, 40). Несколько страниц могут включать некоторое перекрытие в результаты. Чтобы предотвратить дублирование, см. раздел некстоффсет. Используйте этот параметр только с API изображений. Не указывайте этот параметр при вызове API изображений тенденций или Поиск в Интернете API. | Короткое целое без знака | Нет |
| q | Условие запроса поиска пользователя. Термин не может быть пустым. Чтобы улучшить релевантность запроса Insights (см. инсигхтстокен), следует всегда включать термин запроса пользователя. ПРИМЕЧАНИЕ. Если запрос поступает с рынка, для которого политика для взрослых Bing требует параметра safeSearch со значением Strict, Bing игнорирует значение safeSearch и использует Strict. Список поддерживаемых кодов языков см. в статье Поддерживаемые языки Bing. Чтобы указать 2-буквенный код, присвойте этому параметру код языка ISO 639-1. Этот параметр и заголовок Accept-Language являются взаимоисключающими — не указывайте оба значения. Строка пользовательского интерфейса — это строка, которая используется как метка в пользовательском интерфейсе. Есть несколько строк пользовательского интерфейса в объектах ответа JSON. Кроме того, все ссылки на свойства Bing.com в объектах ответа применяют указанный язык. | Строка | Нет |
Фильтрация параметров запроса
Ниже приведены необязательные параметры запроса фильтра, которые можно использовать для фильтрации изображений, возвращаемых Bing. К параметрам запроса нужно применить кодировку URL.
Используйте эти параметры только с Поиск изображений API. Не указывайте эти параметры при вызове API изображений тенденций или API Поиск в Интернете.
Максимальный размер файла, который можно указать, составляет 520 192 байт. Если указать большее значение, API будет использовать 520 192. Возможно, ответ может содержать изображения, которые немного больше указанного максимума.
Вы можете указать этот фильтр и minFileSize отфильтровать изображения в диапазоне размеров файлов.
Вы можете указать этот фильтр и minHeight отфильтровать изображения в диапазоне высоты.
Этот фильтр и height Фильтр являются взаимоисключающими.
Вы можете указать этот фильтр и maxWidth отфильтровать изображения в диапазоне ширины.
Этот фильтр и width Фильтр являются взаимоисключающими.
Максимальный размер файла, который можно указать, составляет 520 192 байт. Если указать большее значение, API будет использовать 520 192. Возможно, ответ может содержать изображения, которые немного меньше указанного минимума.
Вы можете указать этот фильтр и maxFileSize отфильтровать изображения в диапазоне размеров файлов.
Вы можете указать этот фильтр и maxHeight отфильтровать изображения в диапазоне высоты.
Этот фильтр и height Фильтр являются взаимоисключающими.
Вы можете указать этот фильтр и maxWidth отфильтровать изображения в диапазоне ширины.
Этот фильтр можно использовать с size фильтром, чтобы вернуть небольшие изображения шириной 150 пикселей.
Объекты Response
Для обеспечения соответствия новой директиве по защите авторских прав (ЕС), веб-интерфейсам Bing, новостям, видео, изображениям и всем API пользовательского поиска необходимо исключить часть содержимого из некоторых источников новостей ЕС для французских пользователей. Удаленное содержимое может включать эскизы изображений и видео, обзоры видео и фрагменты, которые сопровождают результаты поиска из этих источников. Как следствие, интерфейсы API Bing могут выработать меньше результатов с эскизами изображений и видео, просматривать видео и фрагменты для французских пользователей.
| Объект | Описание |
|---|---|
| аггрегатеоффер | Определяет список предложений из торговых продавцов, связанных с изображением. |
| аггрегатератинг | Определяет метрики, указывающие, насколько хорошо элемент был оценен другими пользователями. |
| Категория | Определяет категорию изображений тенденций. |
| Ошибка | Определяет возникшую ошибку. |
| ErrorResponse | Объект верхнего уровня, который включается ответ при сбое обработки запроса. |
| Изображение | Определяет изображение, относящееся к запросу. |
| имажекаптион | Определяет заголовок изображения. |
| имажегаллери | Определяет ссылку на веб-страницу, содержащую коллекцию связанных изображений. |
| имажеинсигхтс | Объект верхнего уровня, который включает ответ при завершении запроса Image Insights. |
| Изображения | Объект верхнего уровня, который включает ответ при завершении запроса изображения. |
| имажесмодуле | Определяет список изображений. |
| имажетагсмодуле | Определяет характеристики содержимого, найденного в изображении. |
| инсигхтсметадата | Определяет количество веб-сайтов, на которых можно купить или выполнить другие действия, связанные с изображением. |
| MediaSize | Определяет размер мультимедийного содержимого. |
| нормализедректангле | Определяет область изображения. |
| Инструментирование | Определяет URL-адреса инструментирования Bing. |
| Предложение | Определяет предложение продавца. |
| Организация | Определяет сведения о продавце. |
| Person | Определяет человека. |
| Сведение | Определяет сегмент сведения. |
| Запрос | Определяет строку запроса поиска. |
| Рецепт | Определяет рецепт кулинара. |
| реЦипесмодуле | Определяет список рецептов кулинар. |
| рекогнизедентити | Определяет распознанную сущность. |
| рекогнизедентитиграуп | Определяет группу ранее распознанных сущностей. |
| рекогнизедентитиесмодуле | Определяет список ранее распознанных сущностей. |
| рекогнизедентитирегион | Определяет регион, в котором обнаружена сущность, и список сущностей, которые могут соответствовать ей. |
| релатедколлектионсмодуле | Определяет список ссылок на веб-страницы, содержащие связанные изображения. |
| релатедсеарчесмодуле | Определяет список связанных поисков, сделанных другими пользователями. |
| Тег | Определяет характеристику, найденную в изображении. |
| Thumbnail | Определяет эскиз изображения. |
| Tile | Определяет плитку изображения. |
| трендингимажес | Объект верхнего уровня, который включает ответ при завершении запроса изображений тенденций. |
аггрегатеоффер
Определяет список предложений из торговых продавцов, связанных с изображением.
| Элемент | Описание | Тип |
|---|---|---|
| предполагает | Список предложений из продавцов, имеющих предложения, связанные с изображением. | Предложение[] |
аггрегатератинг
Определяет метрики, указывающие, насколько хорошо элемент был оценен другими пользователями.
17 интересных (и забавных) API для вашего проекта
В этой статье я собрал несколько интересных сервисов с API, многие из которых вы можете использовать как основу для вашего приложения. Другие же отлично подходят как уникальные фичи, которые помогут разнообразить опыт использования вашей программы.
Numbers
Сервис содержит много интересных фактов о числах, которыми можно похвастаться перед друзьями.
Также есть факты о датах и годах.
С помощью этого сервиса можно сделать виджет «Этот день в истории».
База вопросов для викторин
Если вы хотели создать викторину, то вы знаете, насколько сложно найти хорошие вопросы. Теперь же вы можете получать их в удобном формате по одному запросу. Для многих вопросов указана сложность, категория и достоверность вопроса (то есть количество людей, которые посчитали вопрос некорректным).
Получение вопроса: http://jservice.io/api/random?count=1
Пример вопроса (фрагмент):
Чем заняться, когда скучно
Сервис BoredAPI может предложить занятие на любой случай жизни: бесплатные, социальные, доступные везде и так далее.
Колода карт
Теперь для организации виртуальной карточной игры не нужно ничего лишнего. Вы можете создать (перемешанную или нет) колоду, взять карту, задать колоду по кодам карт.
В репозитории проекта вы можете найти картинки карт и мастей, которые можно использовать в своих проектах: https://github.com/crobertsbmw/deckofcards/tree/master/static/img
http.cat
Домашняя страница: https://http.cat
Мои любимые картинки:
Поиск аниме
Здесь вы можете найти большой список аниме с тегами и другой информацией. С помощью этих данных можно сделать, например, подбор интересных тайтлов для пользователя на основе предпочтений: истории просмотров и реакции (понравилось или нет).
Пример работы с API: поиск всех результатов, содержащих слово Tokio : https://kitsu.io/api/edge/anime?filter[text]=tokio
Один из результатов (убраны некоторые аттрибуты):
Картинки с котами, собаками и лисами
Страница будет выглядеть каждый раз по-новому, если в её верхнюю часть поместить картинку, которая будет меняться при каждом новом посещении страницы.
Картинки котиков
https://aws.random.cat/meow — возвращается только ссылка на картинку или гифку. Ссылки случайные и ведут на сторонние сервера.
Каждая картинка из базы имеет номер, но API не даёт номер, а получить картинку по номеру только открыв сайт https://aws.random.cat/view/ и достать картинку из исходного текста страницы. Совсем простенький скрипт для этого (для более быстрого исполнения я не использую re):
Картинки собачек
https://random.dog/woof.json — возвращает размер картинки (или gif или видео) в байтах и ссылку на неё. Все ссылки выглядят как https://random.dog/
Другие варианты запросов:
Картинки лисичек
База знаний о Покемонах
Этот сервис позвляет легко получить информацию о покемонах, их способностях и типах, а также о контенте про покемонов: играх и прочем.
Фрагмент из ответа на запрос информации про Ditto ( https://pokeapi.co/api/v2/pokemon/ditto ):
Be like Bill
В меме «Be like Bill» описываются какие-то положительные качества Билла и в конце звучит рекомендация «Быть как он». API позволяет генерировать картинки с заданными или рандомными текстами.
Bakon Ipsum
Сервис позволяет использовать сгенерированные тексты вместо стандартного Lorem Ipsum. Можно задать количество предложений или параграфов. Пример запроса:
https://baconipsum.com/api/?type=all-meat&sentences=2 — создание текста с 2 предложениями.
Шутки
Под эту категорию подходит сразу несколько сервисов с похожими API, поэтому приведу только примеры запросов к API:
Гиковские шутки (часто про Чака Норриса): https://geek-jokes.sameerkumar.website/api?format=json :
There are only 10 types of people in the world: those that understand binary and those that don’t.
Шутки от папы: curl https://icanhazdadjoke.com :
Why do you never see elephants hiding in trees? Because they’re so good at it.
Шутки с конструкцией сетап-панчлайн: https://official-joke-api.appspot.com/random_joke :
«setup»:»I couldn’t get a reservation at the library. «,»punchline»:»They were fully booked.»
Yes or No
Вся информация о мультсериале «Рик и Морти»
Главная страница: https://rickandmortyapi.com
Содержит в себе информацию о героях, локациях и эпизодах мультсериала. Также имеет библиотеки на многих языках, что облегчает работу с API. Пример работы с API с помощью питоновской библиотеки:
Выводы
В интернете сейчас есть много бесплатных сервисов с API, которые могут разнообразить ваш сайт или послужить основой для реализации интересных фич. Возможно, вы захотите добавить что-то в свой проект прямо сейчас?
UPD. Комментарий читателя Drag13
:
Репозиторий с публичными АПИ (тут их гораздо больше чем в статье, и указаны требования к CORS/AUTH и поддержка https): https://github.com/public-apis/public-apis
API если вы хотите получить эту информацию в виде JSON: https://github.com/davemachado/public-api
Облачные серверы от Маклауд быстрые и безопасные.
Зарегистрируйтесь по ссылке выше или кликнув на баннер и получите 10% скидку на первый месяц аренды сервера любой конфигурации!
