Hacer solicitudes

/v1/search recibe la misma consulta que escribirías en el cuadro de búsqueda, más algunos parámetros. Responde a GET y a POST; los parámetros son los mismos en ambos casos.

Parámetros

Nombre	Por defecto	Significado
`query`	obligatorio	La cadena de búsqueda. La misma sintaxis que en el sitio web; consulta sintaxis de consultas.
`page`	1	Empieza en 1.
`per_page`	100	Hasta el límite de filas de tu plan, y lo mismo vale para `page × per_page`: un plan cubre las primeras N filas de una consulta y la paginación no pasa de ellas (`400 page_too_deep`); `/v1/account` lo indica como `max_per_page`.
`snippets`	desactivado	`1` para incluir el texto coincidente. Consume cuota de fragmentos.
`format`	`json`	Uno de seis; consulta formatos de respuesta.
`columns`	según el formato	Subconjunto, separado por comas, de `domain`, `url`, `rank`, `ranked`, `snippets`.
`delimiter`	`;` / tabulador	Para `csv` y `tsv`.
`header`	desactivado	`1` para añadir una línea de encabezado a `csv` y `tsv`.

GET

curl -H "Authorization: Bearer $KEY" \
     "https://api.publicwww.com/v1/search?query=%22angular.min.js%22&page=2&per_page=50"

Recuerda codificar la consulta para URL. Las comillas, las barras y el + importan.

POST

Los mismos parámetros como cuerpo JSON. Úsalo cuando la consulta sea larga o tenga varias frases: una consulta de varias líneas en una URL choca con los límites de longitud de proxies y clientes mucho antes de que le importe al servidor.

curl https://api.publicwww.com/v1/search \
     -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" \
     -d '{"query": ["\"angular.min.js\"", "\"bootstrap.min.css\""],
          "per_page": 50,
          "snippets": true}'

Un array de frases exige que aparezcan todas, exactamente igual que si se separaran con saltos de línea en la cadena query. En el ejemplo anterior, 278 sitios contienen la primera frase y 99 contienen ambas.

Se entienden los tipos de JSON: true funciona donde la cadena de consulta necesita 1. Si un parámetro aparece tanto en la URL como en el cuerpo, prevalece el del cuerpo.

La respuesta

Campo	Significado
`total`	Cuántos sitios coinciden en todo el índice. Es un recuento real, no una estimación.
`total_pages`	`total` dividido entre `per_page`, redondeado hacia arriba.
`returned`	Cuántas filas contiene realmente esta página.
`truncated`	Si el límite de posiciones visibles de tu plan eliminó alguna.
`took_ms`	Cuánto tardó la búsqueda, en milisegundos.
`results`	Las filas.

Una fila

Campo	Significado
`domain`	El sitio.
`url`	La página en la que se encontró la coincidencia, que en las búsquedas con `depth:` no es la página de inicio.
`rank`	Posición en el ranking; cuanto más baja, más popular. `null` si el sitio no tiene posición.
`ranked`	`false` exactamente cuando `rank` es `null`.
`snippets`	Solo con `snippets=1`. Hasta cinco pares `{"text", "match"}`, donde `match` es lo que coincidió y `text` es eso mismo con el contexto que lo rodea.

Paginación y grandes volúmenes

Pasa de página con page, o pide todo de una vez con un per_page grande: hasta el max_per_page de /v1/account, que en un plan de pago es un millón. No hay un endpoint de exportación aparte; la respuesta se escribe a medida que se construye, así que un millón de filas no implica además un millón de filas retenidas en memoria en algún sitio.

Siguiente Formatos de respuesta