Este documento descreve como usar a API JSON da Pesquisa personalizada do Google.
Como realizar uma solicitação
REST, ou transferência de estado representacional, na API JSON da Pesquisa personalizada é um pouco diferente do REST tradicional. Em vez de fornecer acesso a recursos, a API fornece acesso a um serviço. Dessa forma, a API fornece um URI que atua como extremidade do serviço.
Você pode recuperar resultados de uma pesquisa específica enviando um GET
HTTP
solicitação ao URI. 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 consultas [parameters]
são necessárias para cada solicitação de pesquisa:
- Chave de API: use o parâmetro de consulta
key
para identificar o aplicativo. ID do Mecanismo de Pesquisa Programável: use
cx
para especificar o o Mecanismo de Pesquisa Programável que você quer usar para 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)Consulta de pesquisa: use o parâmetro de consulta
q
para especificar sua expressão de pesquisa.
Todos os outros parâmetros de consulta são opcionais.
Veja um exemplo de uma solicitação que pesquisa um testar o Mecanismo de Pesquisa Programável para palestras:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures
Parâmetros de consulta
Há dois tipos de parâmetros que você pode transmitir na solicitação:
- Parâmetros específicos da API - defina as propriedades da sua pesquisa, como a expressão de pesquisa, o número de resultados, o idioma etc.
- Parâmetros de consulta padrão - define aspectos técnicos da sua solicitação, como os Chave de API.
Todos os valores de parâmetros precisam ser codificados no URL.
Parâmetros de consulta específicos da API
Parâmetros de solicitação que se aplicam especificamente à API JSON da Pesquisa personalizada e definem solicitação de pesquisa são resumidos referência.
Parâmetros de consulta padrão
Os parâmetros de consulta que se aplicam a todas as operações da API JSON da Pesquisa personalizada do Google estão documentados em Parâmetros do sistema.
Dados de resposta
Se a solicitação for bem-sucedida, o servidor responderá com um código de status HTTP 200 OK
.
e os dados de resposta no formato JSON. É possível pesquisar os 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 pesquisas 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.
Pesquisar metadados da solicitação
Os metadados de pesquisa incluem:
url
, que tem informações sobre o modelo do OpenSearch usado para os resultados retornados nessa solicitação.queries
, que é uma matriz de objetos que descrevem as características de possíveis pesquisas. O nome de cada na matriz é o nome de um Papel de consulta do OpenSearch ou um dos dois papéis personalizados definidos por esta API:previousPage
enextPage
. Possíveis objetos de função da consulta incluem:request
: metadados que descrevem a consulta do 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 100 primeiros resultados.
- Quando presente, é sempre uma matriz com apenas um elemento.
previousPage
: metadados que descrevem a consulta a ser usada para o página de resultados anterior.- 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. inclui o nome do mecanismo de pesquisa e
todos os objetos de atributo fornecidos para
refinando uma pesquisa.
Resultados da pesquisa
A matriz items
contém os resultados reais da pesquisa. A pesquisa
resultados incluem o URL, título e snippets de texto que descrevem o resultado. Em
Além disso, eles podem conter rich snippet
se aplicável.
Se os resultados da pesquisa incluem uma propriedade promotions
, ela contém
um conjunto de promoções.
REST a partir de JavaScript
Você pode invocar a API JSON da Pesquisa personalizada do Google usando REST a partir de JavaScript, usando a
parâmetro de consulta callback
e uma função de callback. Isso permite que você
para criar aplicativos avançados que mostram dados do Mecanismo de Pesquisa Programável sem gravar
no código do lado do servidor.
O exemplo a seguir usa essa abordagem para mostrar a primeira página da pesquisa resultados para a consulta 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>