Usar o REST para invocar a API

Este documento descreve como usar a API JSON Custom Search.

Fazer uma solicitação

A REST, ou transferência de estado representacional, na API Custom Search JSON é um pouco diferente das APIs RESTful usuais. 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 do serviço.

É possível recuperar resultados de uma pesquisa específica enviando 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 necessários para cada solicitação de pesquisa:

  • Chave de API: use o parâmetro de consulta key para identificar seu app.

    • ID do Mecanismo de Pesquisa Programável: use cx para 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).

  • Consulta de pesquisa: use o parâmetro de consulta q para especificar a expressão de pesquisa.

Todos os outros parâmetros de consulta são opcionais.

Confira um exemplo de solicitação que pesquisa um Mecanismo de Pesquisa Programável de teste 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 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 sua 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. É possível consultar 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 da pesquisa incluem:

  • A propriedade url, que tem informações sobre o modelo do OpenSearch usado para os resultados retornados nesta solicitação.
  • Propriedade queries, que é uma matriz de objetos que descreve as características de possíveis pesquisas. O nome de cada objeto no array é 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 função de consulta incluem:
    • request: metadados que descrevem a consulta para o conjunto de resultados atual.
    • 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 para a 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 para a 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. Ele inclui o nome do mecanismo de pesquisa e todos os objetos de faceta que ele fornece 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 trechos de texto que descrevem o resultado. Além disso, eles podem conter informações de snippet enriquecido, 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 Custom Search JSON usando REST do JavaScript, com o parâmetro de consulta callback e uma função de callback. Isso permite criar aplicativos avançados que mostram 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 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>