Este documento ajudará você a se familiarizar com a API Custom Search JSON e como ela é usada.
Antes de começar
Criar Mecanismo de Pesquisa Programável
Ao chamar o usuário da 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 da criação, você pode encontrar o ID do mecanismo de pesquisa na seção Básico da página Visão geral. Esse é o parâmetro cx usado pela API.
Identifique seu aplicativo para o Google com uma chave de API
A API Custom Search JSON requer o uso de uma chave de API. Uma chave de API é uma maneira de identificar seu cliente para o Google.
- Usuários do Mecanismo de Pesquisa Programável (edição sem custo financeiro): acessar uma chave
Quando você tem uma chave de API, seu aplicativo pode adicionar o parâmetro de consulta key=yourAPIKey a todos os URLs das solicitações. É seguro incorporar a chave de API a URLs, sem precisar de codificação.
Perspectiva geral sobre APIs
Operações de API
Há apenas um método de chamada na API JSON da Pesquisa personalizada:
| 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 à API JSON da Pesquisa personalizada é 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 JSON da Pesquisa personalizada define duas propriedades 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 segurança da pesquisa 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 descobrir 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 de cse.list.
Para saber como usar a API via solicitações HTTP, acesse Como usar REST.