В этом документе описывается, как использовать JSON API пользовательского поиска.
Сделать запрос
REST, или передача репрезентативного состояния , в JSON API пользовательского поиска несколько отличается от традиционного REST. Вместо предоставления доступа к ресурсам API предоставляет доступ к службе. В результате API предоставляет единый URI, который действует как конечная точка службы.
Вы можете получить результаты для определенного поиска, отправив HTTP- GET
на его URI. Вы передаете детали поискового запроса в качестве параметров запроса. Формат URI пользовательского поиска JSON API:
https://www.googleapis.com/customsearch/v1?[parameters]
Для каждого поискового запроса требуются три запроса [parameters]
:
- Ключ API . Используйте
key
параметр запроса для идентификации вашего приложения . Идентификатор программируемой поисковой системы — используйте
cx
, чтобы указать программируемую поисковую систему, которую вы хотите использовать для выполнения этого поиска. Поисковая система должна быть создана с помощью Панели управления . Примечание. Идентификатор поисковой системы (cx) может иметь другой формат (например, 8ac1ab64606d234f1).Поисковый запрос — используйте параметр запроса
q
, чтобы указать поисковое выражение.
Все остальные параметры запроса являются необязательными.
Вот пример запроса, который ищет лекции в тестовой программируемой поисковой системе:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures
Параметры запроса
Есть два типа параметров, которые вы можете передать в своем запросе:
- Параметры, специфичные для API — определяют свойства вашего поиска, такие как выражение поиска, количество результатов, язык и т. д.
- Стандартные параметры запроса — укажите технические аспекты вашего запроса, такие как ключ API.
Все значения параметров должны быть закодированы в URL.
Параметры запроса API
Параметры запроса, которые применяются конкретно к JSON API пользовательского поиска и определяют ваш поисковый запрос, приведены в справке .
Стандартные параметры запроса
Параметры запроса, применимые ко всем операциям JSON API пользовательского поиска, задокументированы в разделе Системные параметры .
Данные ответа
Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK
и данными ответа в формате JSON. Вы можете посмотреть структуру данных ответа в справочнике .
Данные ответа представляют собой объект JSON, который включает три типа свойств:
- Метаданные, описывающие запрошенный поиск (и, возможно, связанные поисковые запросы)
- Метаданные, описывающие программируемую поисковую систему
- Результаты поиска
Подробное описание каждого свойства смотрите в ссылке .
Метаданные поискового запроса
Метаданные поиска включают:
-
url
, которое содержит информацию о шаблоне OpenSearch , используемом для результатов, возвращаемых в этом запросе. - Свойство
queries
, представляющее собой массив объектов, описывающих характеристики возможных поисков. Имя каждого объекта в массиве — это либо имя роли запроса OpenSearch , либо одна из двух настраиваемых ролей, определенных этим API:previousPage
иnextPage
. Возможные объекты роли запроса включают:-
request
: метаданные, описывающие запрос для текущего набора результатов.- Эта роль всегда присутствует в ответе.
- Это всегда массив с одним элементом.
-
nextPage
: метаданные, описывающие запрос для использования на следующей странице результатов.- Эта роль отсутствует, если текущие результаты являются последней страницей. Примечание. Этот API возвращает только первые 100 результатов.
- Когда он присутствует, это всегда массив только с одним элементом.
-
previousPage
страница : метаданные, описывающие запрос для использования на предыдущей странице результатов.- Не присутствует, если текущие результаты являются первой страницей.
- Когда он присутствует, это всегда массив только с одним элементом.
-
Метаданные поисковой системы
Свойство context
содержит метаданные, описывающие поисковую систему, выполнившую поисковый запрос. Он включает имя поисковой системы и любые фасетные объекты , которые она предоставляет для уточнения поиска.
Результаты поиска
Массив items
содержит фактические результаты поиска. Результаты поиска включают URL-адрес, заголовок и текстовые фрагменты, описывающие результат. Кроме того, они могут содержать расширенные фрагменты информации, если это применимо.
Если результаты поиска содержат свойство promotions
, оно содержит набор рекламных акций .
ОТДЫХ из JavaScript
Вы можете вызвать JSON API пользовательского поиска с помощью REST из JavaScript, используя параметр запроса callback
и функцию обратного вызова. Это позволяет вам писать многофункциональные приложения, отображающие данные программируемой поисковой системы, без написания кода на стороне сервера.
В следующем примере этот подход используется для отображения первой страницы результатов поиска по запросу cars :
<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
<div id="content"></div>
<script>
function hndlr(response) {
for (var i = 0; i < response.items.length; i++) {
var item = response.items[i];
// Make sure HTML in item.htmlTitle is escaped.
document.getElementById("content").append(
document.createElement("br"),
document.createTextNode(item.htmlTitle)
);
}
}
</script>
<script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=cars&callback=hndlr">
</script>
</body>
</html>