API Custom Search JSON: introdução

Este documento vai ajudar você a se familiarizar com a API Custom Search JSON e o uso dela.

Antes de começar

Criar um Mecanismo de Pesquisa Programável

Ao chamar a API, o usuário emite solicitações para uma instância atual do Mecanismo de Pesquisa Programável. Portanto, antes de usar a API, você precisa criar uma no Painel de controle. Siga o tutorial para saber mais sobre as diferentes opções de configuração. Depois de criá-lo, você vai encontrar o ID do mecanismo de pesquisa na seção Informações básicas da página Visão geral. Esse é o parâmetro cx usado pela API.

Identificar seu aplicativo para o Google com uma chave de API

A API Custom Search JSON exige o uso de uma chave de API. Uma chave de API é uma forma de identificar seu cliente para o Google.

Quando você tem uma chave de API, seu app pode adicionar o parâmetro de consulta key=yourAPIKey ao final de todos os URLs de solicitação. É seguro incorporar a chave de API a URLs. Não é necessário codificá-la.

Visão geral da API

Operações de API

Há apenas um método para invocar na API Custom Search JSON:

Operação Descrição Mapeamento HTTP REST
list Retorna os resultados da pesquisa solicitados de um Mecanismo de Pesquisa Programável. GET

Modelo de dados de API

O resultado de uma consulta de pesquisa para a API Custom Search JSON é um objeto JSON que inclui três tipos de dados:

  • 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

Consulte a seção "Dados de resposta" de Como usar REST para mais detalhes.

O modelo de dados é baseado na Especificação do OpenSearch 1.1. Além das propriedades padrão do OpenSearch, a API Custom Search JSON define duas propriedades personalizadas e duas funções de consulta personalizadas:

  • Propriedades personalizadas
    • cx: o identificador do Mecanismo de Pesquisa Programável.
    • safe: uma descrição do nível de pesquisa segura para filtrar os resultados retornados.
  • Papéis de consulta personalizados
    • nextPage: um papel que indica que a consulta pode ser usada para acessar a próxima página lógica de resultados, se houver.
    • previousPage: um papel que indica que a consulta pode ser usada para acessar a página lógica anterior de resultados, se houver.

Testar

Para testar e ver o que a API pode fazer sem escrever nenhum código, acesse a ferramenta "Testar esta API".

Para uma descrição completa dos parâmetros, acesse a referência cse.list.

Para saber como usar a API por solicitações HTTP, acesse Como usar REST.