Como usar o REST para chamar a API

Este documento descreve como usar a API JSON da Pesquisa personalizada.

Como fazer 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.

Recupere os resultados de uma pesquisa específica enviando uma solicitação GET HTTP ao URI. Você transmite os detalhes da solicitação de pesquisa como parâmetros de consulta. O formato do URI da API JSON da Pesquisa personalizada é:

https://www.googleapis.com/customsearch/v1?[parameters]

São necessárias três consultas [parameters] para cada solicitação de pesquisa:

  • Chave de API: use o parâmetro de consulta key para identificar seu aplicativo.
  • ID do Mecanismo de Pesquisa Programável: use cx para especificar o Mecanismo de Pesquisa Programável que você quer usar para fazer 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.

Confira 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=lectures

Parâmetros de consulta

É possível transmitir dois tipos de parâmetros na solicitação:

  • Parâmetros específicos da API: defina propriedades da pesquisa, como expressão de pesquisa, número de resultados, idioma etc.
  • Parâmetros de consulta padrão: defina 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 JSON da Pesquisa personalizada 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 JSON de Pesquisa personalizada 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. Você pode procurar 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 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 OpenSearch usado para os resultados retornados nessa solicitação.
  • queries, que é uma matriz de objetos que descrevem as características de pesquisas possíveis. O nome de cada objeto na matriz é o nome de um papel de consulta do OpenSearch ou um dos dois papéis personalizados definidos por essa API: previousPage e nextPage. Os possíveis objetos de papel da 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 até os 100 primeiros resultados apenas.
        • Quando presente, é sempre uma matriz com apenas um elemento.
    • previousPage: metadados que descrevem a consulta a ser usada na 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 executou a consulta. Ela inclui o nome do mecanismo de pesquisa e todos os objetos de atributos fornecidos para refinar uma pesquisa.

Resultados da pesquisa

A matriz items contém os resultados reais 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 incluem uma propriedade promotions, ela contém um conjunto de promoções.

REST a partir de JavaScript

É possível invocar a API JSON da Pesquisa personalizada usando o REST a partir de JavaScript, o parâmetro de consulta callback e uma função de callback. Isso permite criar aplicativos avançados que exibem dados do Mecanismo de Pesquisa Programável sem escrever códigos do lado do servidor.

O exemplo a seguir usa essa abordagem para mostrar a primeira página de resultados de pesquisa 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>