En este documento, se describe cómo usar la API de Custom Search JSON.
Haz una solicitud
REST, o transferencia de estado representacional, en la API de Custom Search JSON es algo diferente de las APIs RESTful habituales. En lugar de proporcionar acceso a los recursos, la API proporciona acceso a un servicio. Como resultado, la API proporciona un solo URI que actúa como el extremo del servicio.
Para recuperar los resultados de una búsqueda en particular, envía una solicitud GET HTTP a su URI. Pasas los detalles de la solicitud de búsqueda como parámetros de búsqueda. El formato del 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
keypara identificar tu aplicación.- ID de Motor de Búsqueda Programable: Usa
cxpara especificar el Motor de Búsqueda Programable que deseas 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).
- ID de Motor de Búsqueda Programable: Usa
Búsqueda: Usa el parámetro de consulta
qpara especificar tu expresión de búsqueda.
Todos los demás parámetros de consulta son opcionales.
Este es un ejemplo de una solicitud que busca conferencias 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=lecturesParámetros de consulta
Existen dos tipos de parámetros que puedes pasar en tu solicitud:
- Parámetros específicos de la API: Definen 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 aspectos técnicos de tu solicitud, como la clave de API.
Todos los valores de los parámetros deben estar codificados como URL.
Parámetros de consulta específicos de la API
En la referencia, se resumen los parámetros de solicitud que se aplican específicamente a la API de Custom Search JSON y definen tu solicitud de búsqueda.
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 la respuesta en formato JSON. Puedes buscar la estructura de datos de la respuesta en la referencia.
Los datos de la respuesta son un objeto JSON que incluye tres tipos de propiedades:
- Metadatos que describen la búsqueda solicitada (y, posiblemente, las solicitudes de búsqueda 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 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 muestran en esta solicitud - La propiedad
queries, que es un array de objetos que describen las características de las búsquedas posibles. El nombre de cada objeto del array es el nombre de un rol de consulta de OpenSearch o uno de los dos roles personalizados que define esta API:previousPageynextPage. Entre los posibles objetos de roles de consulta, se incluyen los siguientes:request: Son metadatos que describen la consulta del conjunto de resultados actual.- 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: Son 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 de motores 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 cualquier objeto de faceta que proporcione 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, esta contiene un conjunto de promociones.
REST desde 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 para la 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>