Anfragen senden

/v1/search nimmt dieselbe Suchanfrage entgegen, die Sie in das Suchfeld eingeben würden, plus einige Parameter. Der Endpunkt antwortet auf GET und auf POST; die Parameter sind in beiden Fällen dieselben.

Parameter

Name	Standard	Bedeutung
`query`	erforderlich	Die Suchzeichenfolge. Dieselbe Syntax wie auf der Website - siehe Suchsyntax.
`page`	1	Beginnt bei 1.
`per_page`	100	Bis zum Zeilenlimit Ihres Tarifs, und das gilt auch für `page × per_page`: Ein Tarif deckt die ersten N Zeilen einer Suchanfrage ab, und das Blättern geht nicht darüber hinaus (`400 page_too_deep`); `/v1/account` meldet den Wert als `max_per_page`.
`snippets`	aus	`1`, um den passenden Text mitzuliefern. Verbraucht Schnipsel-Kontingent.
`format`	`json`	Eines von sechs - siehe Antwortformate.
`columns`	je nach Format	Kommagetrennte Auswahl aus `domain`, `url`, `rank`, `ranked`, `snippets`.
`delimiter`	`;` / Tab	Für `csv` und `tsv`.
`header`	aus	`1`, um `csv` und `tsv` eine Kopfzeile voranzustellen.

GET

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

Denken Sie daran, die Suchanfrage URL-zu-kodieren. Anführungszeichen, Schrägstriche und + spielen alle eine Rolle.

POST

Dieselben Parameter als JSON-Body. Verwenden Sie das, wenn die Suchanfrage lang ist oder mehrere Phrasen enthält: Eine mehrzeilige Suchanfrage in einer URL stößt bei Proxys und Clients an Längengrenzen, lange bevor der Server sich daran stört.

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

Ein Array von Phrasen bedeutet: alle davon - genau so, als würden sie im query-String durch Zeilenumbrüche getrennt. Im Beispiel oben enthalten 278 Websites die erste Phrase und 99 beide.

JSON-Typen werden verstanden: true funktioniert dort, wo der Query-String 1 braucht. Wird ein Parameter sowohl in der URL als auch im Body angegeben, gilt der Body.

Die Antwort

Feld	Bedeutung
`total`	Wie viele Websites im gesamten Index passen. Eine echte Zählung, keine Schätzung.
`total_pages`	`total` geteilt durch `per_page`, aufgerundet.
`returned`	Wie viele Zeilen diese Seite tatsächlich enthält.
`truncated`	Ob das Positionslimit Ihres Tarifs Zeilen entfernt hat.
`took_ms`	Wie lange die Suche gedauert hat, in Millisekunden.
`results`	Die Zeilen.

Eine Zeile

Feld	Bedeutung
`domain`	Die Website.
`url`	Die Seite, auf der der Treffer gefunden wurde - bei `depth:`-Suchen nicht die Startseite.
`rank`	Position in der Rangliste; je niedriger, desto populärer. `null`, wenn die Website keinen Rang hat.
`ranked`	`false` genau dann, wenn `rank` `null` ist.
`snippets`	Nur mit `snippets=1`. Bis zu fünf `{"text", "match"}`-Paare, wobei `match` der Treffer ist und `text` der Treffer mit umgebendem Kontext.

Blättern und Massenabfragen

Blättern Sie mit page, oder fordern Sie alles auf einmal mit einem großen per_page an - bis zu max_per_page aus /v1/account, das in einem kostenpflichtigen Tarif eine Million beträgt. Einen separaten Export-Endpunkt gibt es nicht; die Antwort wird geschrieben, während sie entsteht, sodass eine Million Zeilen nicht zugleich eine Million Zeilen irgendwo im Speicher bedeuten.

Weiter Antwortformate