Este documento descreve como usar a API Custom Search JSON.
Fazer uma solicitação
A REST, ou Representational State Transfer, na API Custom Search JSON é um pouco diferente das APIs RESTful comuns. Em vez de fornecer acesso a recursos, a API fornece acesso a um serviço. Como resultado, a API fornece um único URI que atua como o endpoint de serviço.
Para recuperar os resultados de uma pesquisa específica, envie uma solicitação HTTP GET
para o URI dela. Você transmite os detalhes da solicitação de pesquisa como parâmetros de consulta. O formato do URI da API Custom Search JSON é:
https://www.googleapis.com/customsearch/v1?[parameters]
Três [parameters] de consulta são obrigatórios em cada solicitação de pesquisa:
Chave de API: use o parâmetro de consulta
keypara identificar seu aplicativo.- ID do Mecanismo de Pesquisa Programável: use
cxpara especificar o Mecanismo de Pesquisa Programável que você quer usar para realizar essa pesquisa. O mecanismo de pesquisa precisa ser criado com o Painel de controle. Observação: o ID do mecanismo de pesquisa (cx) pode ter um formato diferente (por exemplo, 8ac1ab64606d234f1).
- ID do Mecanismo de Pesquisa Programável: use
Consulta de pesquisa: use o parâmetro de consulta
qpara especificar sua expressão de pesquisa.
Todos os outros parâmetros de consulta são opcionais.
Veja um exemplo de solicitação que pesquisa palestras em um Mecanismo de Pesquisa Programável de teste:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lecturesParâmetros de consulta
Há dois tipos de parâmetros que podem ser transmitidos na solicitação:
- Parâmetros específicos da API: definem propriedades da pesquisa, como a expressão de pesquisa, o número de resultados, o idioma etc.
- Parâmetros de consulta padrão: definem aspectos técnicos da solicitação, como a chave de API.
Todos os valores de parâmetros precisam ser codificados no URL.
Parâmetros de consulta específicos da API
Os parâmetros de solicitação que se aplicam especificamente à API Custom Search JSON e definem sua solicitação de pesquisa estão resumidos na referência.
Parâmetros de consulta padrão
Os parâmetros de consulta que se aplicam a todas as operações da API Custom Search JSON estão documentados em Parâmetros do sistema.
Dados de resposta
Se a solicitação for bem-sucedida, o servidor vai responder com um código de status HTTP 200 OK
e os dados de resposta no formato JSON. Consulte a estrutura de dados de resposta na referência.
Os dados de resposta são um objeto JSON que inclui três tipos de propriedades:
- Metadados que descrevem a pesquisa solicitada (e, possivelmente, solicitações de pesquisa relacionadas)
- Metadados que descrevem o Mecanismo de Pesquisa Programável
- Resultados da pesquisa
Para uma descrição detalhada de cada propriedade, consulte a referência.
Metadados da solicitação de pesquisa
Os metadados de pesquisa incluem:
- Propriedade
url, que tem informações sobre o modelo do OpenSearch usado para os resultados retornados nessa solicitação. - Propriedade
queries, que é uma matriz de objetos que descrevem as características das possíveis pesquisas. O nome de cada objeto na matriz é o nome de um papel de consulta do OpenSearch ou uma das duas funções personalizadas definidas por esta API:previousPageenextPage. Os possíveis objetos de função de consulta incluem:request: metadados que descrevem a consulta para o conjunto atual de resultados.- Esta função está sempre presente na resposta.
- Está sempre na matriz com apenas um elemento.
nextPage: metadados que descrevem a consulta a ser usada na próxima página de resultados.- Esta função não está presente na última página de resultados. Observação: essa API retorna apenas os primeiros 100 resultados.
- Quando presente, é sempre uma matriz com apenas um elemento.
previousPage: metadados que descrevem a consulta a ser usada na página anterior de resultados.- Não está presente na primeira página de resultados.
- Quando presente, é sempre uma matriz com apenas um elemento.
Metadados do mecanismo de pesquisa
A propriedade context tem metadados que descrevem o mecanismo de pesquisa que realizou
a consulta de pesquisa. Ele inclui o nome do mecanismo de pesquisa e todos os objetos de atributo que ele fornece para refinar uma pesquisa.
Resultados da pesquisa
A matriz items contém os resultados da pesquisa. Os resultados da pesquisa incluem
o URL, o título e os snippets de texto que descrevem o resultado. Além disso, eles podem
conter informações de rich snippet, se
aplicável.
Se os resultados da pesquisa incluírem uma propriedade promotions, ela vai conter um conjunto de
promoções.
REST a partir de JavaScript
É possível invocar a API Custom Search JSON usando REST do JavaScript, com o
parâmetro de consulta callback e uma função de callback. Isso permite que você escreva aplicativos
avançados que mostram dados do Mecanismo de Pesquisa Programável sem escrever nenhum
código do lado do servidor.
O exemplo a seguir usa essa abordagem para exibir a primeira página de resultados da pesquisa para a consulta lecture:
<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
<div id="content"></div>
<p id="demo"></p>
<script>
function hndlr(response) {
if (response.items == null) {
document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
} else {
for (var i = 1; 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=lecture&callback=hndlr">
</script>
</body>
</html>