Envoyer des requêtes

/v1/search accepte la même requête que celle que vous saisiriez dans le champ de recherche, plus quelques paramètres. Il répond à GET et à POST ; les paramètres sont les mêmes dans les deux cas.

Paramètres

Nom	Par défaut	Signification
`query`	obligatoire	La chaîne de recherche. Même syntaxe que sur le site - voir la syntaxe des requêtes.
`page`	1	Numérotation à partir de 1.
`per_page`	100	Jusqu’à la limite de lignes de votre forfait, de même que `page × per_page` : un forfait couvre les N premières lignes d’une requête, et la pagination ne va pas au-delà (`400 page_too_deep`) ; `/v1/account` l’indique sous le nom `max_per_page`.
`snippets`	désactivé	`1` pour inclure le texte correspondant. Consomme le quota d’extraits.
`format`	`json`	L’un des six - voir les formats de réponse.
`columns`	selon le format	Sous-ensemble, séparé par des virgules, de `domain`, `url`, `rank`, `ranked`, `snippets`.
`delimiter`	`;` / tabulation	Pour `csv` et `tsv`.
`header`	désactivé	`1` pour ajouter une ligne d’en-tête en `csv` et `tsv`.

GET

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

Pensez à encoder la requête pour l’URL. Les guillemets, les barres obliques et le + ont tous leur importance.

POST

Les mêmes paramètres, dans un corps JSON. Utilisez-le lorsque la requête est longue ou contient plusieurs expressions : une requête sur plusieurs lignes placée dans une URL se heurte aux limites de longueur des proxys et des clients bien avant que le serveur n’y trouve à redire.

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 tableau d’expressions signifie « toutes à la fois », exactement comme si vous les sépariez par des sauts de ligne dans la chaîne query. Dans l’exemple ci-dessus, 278 sites contiennent la première expression et 99 contiennent les deux.

Les types JSON sont reconnus : true fonctionne là où l’URL demande 1. Lorsqu’un paramètre figure à la fois dans l’URL et dans le corps, c’est le corps qui l’emporte.

La réponse

Champ	Signification
`total`	Le nombre de sites correspondants dans tout l’index. Un décompte réel, pas une estimation.
`total_pages`	`total` divisé par `per_page`, arrondi à l’entier supérieur.
`returned`	Le nombre de lignes réellement contenues dans cette page.
`truncated`	Indique si la limite de positions dévoilées de votre forfait en a supprimé.
`took_ms`	La durée de la recherche, en millisecondes.
`results`	Les lignes.

Une ligne

Champ	Signification
`domain`	Le site.
`url`	La page sur laquelle la correspondance a été trouvée ; pour les recherches `depth:`, ce n’est pas la page d’accueil.
`rank`	La position dans le classement ; plus elle est basse, plus le site est populaire. `null` lorsque le site n’a pas de rang.
`ranked`	`false` exactement lorsque `rank` vaut `null`.
`snippets`	Uniquement avec `snippets=1`. Jusqu’à cinq paires `{"text", "match"}`, où `match` est ce qui a correspondu et `text` le même passage avec son contexte.

Pagination et volumes importants

Parcourez les pages avec page, ou demandez tout d’un coup avec un per_page élevé - jusqu’au max_per_page indiqué par /v1/account, soit un million avec un forfait payant. Il n’existe pas de point de terminaison d’export distinct ; la réponse est écrite au fur et à mesure de sa construction : un million de lignes ne signifie donc pas un million de lignes gardées en mémoire quelque part.

Suivant Formats de réponse