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 de REST tradicional. En vez de proporcionar acceso a los recursos, la API proporciona acceso a un servicio. Como resultado, la API proporciona un único URI que actúa como el extremo del servicio.

Puedes recuperar los resultados de una búsqueda específica enviando un GET HTTP. solicitud 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 con cada solicitud de búsqueda:

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

  • Programmable Search Engine ID: Usa cx para especificar el Motor de Búsqueda Programable que quieres usar para realizar esta búsqueda. El motor de búsqueda se debe crear 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 tu 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 un Prueba Motor de Búsqueda Programable para las clases:

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

Parámetros de consulta

Hay dos tipos de parámetros que puedes pasar en tu solicitud:

  • 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: define aspectos técnicos de tu solicitud, como el 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

Solicita parámetros que se apliquen específicamente a la API de Custom Search JSON y define tu solicitudes de búsqueda se resumen en el referencia.

Parámetros de búsqueda estándar

Los parámetros de consulta 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 los datos de las respuestas 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úsqueda relacionada)
  • 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 búsqueda incluyen lo siguiente:

  • La propiedad url, que tiene Información sobre la plantilla de OpenSearch que se usa para los resultados que se devuelven en esta solicitud.
  • queries, que es un array de que describen las características de posibles búsquedas. Nombre de cada objeto del array es el nombre de un Función de consulta de OpenSearch o uno de los dos roles personalizados definidos por esta API: previousPage y nextPage. Posibles objetos de función de consulta incluyen:
    • request: metadatos que describen la búsqueda del conjunto actual de resultados.
      • Este rol siempre está presente en la respuesta.
      • Siempre es un array con un solo elemento.
      • nextPage: Son metadatos que describen la consulta que se usará para 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 el 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 de los motores de búsqueda

La propiedad context tiene metadatos que describen el motor de búsqueda que realizó la consulta de búsqueda. Incluye el nombre del motor de búsqueda y cualquier objeto 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. La búsqueda resultados incluyen la URL, el título y fragmentos de texto que los describen. En también pueden contener fragmentos enriquecidos información, si corresponde.

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

REST desde JavaScript

Puedes invocar la API de Custom Search JSON con REST de JavaScript, con 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 código del servidor.

En el siguiente ejemplo, se usa este enfoque para mostrar la primera página de la búsqueda Resultados para la 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>