Cómo usar REST para invocar la API

En este documento, se describe cómo usar la API de Custom Search JSON.

Cómo realizar una solicitud

REST, o transferencia de estado representacional, en la API de Custom Search JSON es algo diferente a REST tradicional. En lugar de brindar acceso a los recursos, la API brinda acceso a un servicio. Como resultado, la API proporciona un único URI que actúa como extremo del servicio.

Puedes recuperar resultados para una búsqueda en particular si envías una solicitud GET HTTP a su URI. Debes pasar los detalles de la solicitud de búsqueda como parámetros de consulta. El formato para el URI de la API de Custom Search JSON es el siguiente:

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

Se requieren tres [parameters] de consulta para cada solicitud de búsqueda:

• Clave de API: usa el parámetro de consulta key para identificar tu aplicación.

• ID del Motor de Búsqueda Programable: Usa cx para especificar el Motor de Búsqueda Programable que quieres usar para realizar esta búsqueda. Se debe crear el motor de búsqueda con el Panel de control. Nota: El ID del motor de búsqueda (cx) puede tener un formato diferente (p. ej., 8ac1ab64606d234f1).

• Búsqueda: Usa el parámetro de búsqueda q para especificar la expresión de búsqueda.

Todos los demás parámetros de consulta son opcionales.

A continuación, se muestra un ejemplo de una solicitud que busca clases en un Motor de Búsqueda Programable de prueba:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

Nota: El límite de longitud de la solicitud de búsqueda debe ser de 2,048 caracteres.

Parámetros de consulta

En una solicitud, puedes pasar dos tipos de parámetros:

• Parámetros específicos de la API: Define las propiedades de tu búsqueda, como la expresión de búsqueda, la cantidad de resultados, el idioma, etcétera.
• Parámetros de consulta estándar: definen los aspectos técnicos de tu solicitud, como la clave de API.

Todos los valores de los parámetros deben estar codificados en formato URL.

Parámetros de consulta específicos de la API

Los parámetros de solicitud que se aplican específicamente a la API de Custom Search JSON y definen tu solicitud de búsqueda se resumen en la referencia.

Parámetros de búsqueda estándar

Los parámetros de búsqueda que se aplican a todas las operaciones de la API de Custom Search JSON se documentan en Parámetros del sistema.

Datos de respuesta

Si la solicitud se realiza correctamente, el servidor responde con un código de estado HTTP 200 OK y los datos de respuesta en formato JSON. Puedes buscar la estructura de datos de respuesta en la referencia.

Los datos de respuesta son un objeto JSON que incluye tres tipos de propiedades:

• Metadatos que describen la búsqueda solicitada (y, posiblemente, solicitudes de búsquedas relacionadas)
• Metadatos que describen el Motor de Búsqueda Programable
• Resultados de la búsqueda

Para obtener una descripción detallada de cada propiedad, consulta la referencia.

Metadatos de la solicitud de búsqueda

Los metadatos de la búsqueda incluyen lo siguiente:

• La propiedad url, que incluye información sobre la plantilla de OpenSearch que se usó para los resultados que se muestran en esta solicitud
• Propiedad queries, que es un array de objetos que describen las características de búsquedas posibles. El nombre de cada objeto del arreglo es el nombre de una función de consulta de OpenSearch o una de las dos funciones personalizadas definidas por esta API: previousPage y nextPage. Entre los objetos posibles de la función de consulta, se incluyen los siguientes:
  • request: Son los metadatos que describen la consulta para el conjunto actual de resultados.
    • Esta función siempre está presente en la respuesta.
    • Siempre es un array con un solo elemento.
    • nextPage: Metadatos que describen la consulta que se usará en la siguiente página de resultados
      • Este rol no está presente si los resultados actuales son la última página. Nota: Esta API solo muestra los primeros 100 resultados.
      • Cuando está presente, siempre es un array con un solo elemento.
  • previousPage: Metadatos que describen la consulta que se usará para la página de resultados anterior
    • No está presente si los resultados actuales son la primera página.
    • Cuando está presente, siempre es un array con un solo elemento.

Metadatos del motor de búsqueda

La propiedad context tiene metadatos que describen el motor de búsqueda que realizó la búsqueda. Incluye el nombre del motor de búsqueda y los objetos de faceta que proporciona para definir mejor una búsqueda.

Resultados de la búsqueda

El array items contiene los resultados de la búsqueda reales. Los resultados de la búsqueda incluyen la URL, el título y los fragmentos de texto que describen el resultado. Además, pueden contener información de fragmentos enriquecidos, si corresponde.

Si los resultados de la búsqueda incluyen una propiedad promotions, es un conjunto de promociones.

REST de JavaScript

Puedes invocar la API de Custom Search JSON con REST desde JavaScript, mediante el parámetro de consulta callback y una función de devolución de llamada. Esto te permite escribir aplicaciones enriquecidas que muestren datos del Motor de Búsqueda Programable sin escribir ningún código del servidor.

En el siguiente ejemplo, se usa este enfoque para mostrar la primera página de resultados de la búsqueda autos:

<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>