Making requests

/v1/search takes the same query you would type into the search box, plus a few parameters. It answers to GET and to POST; the parameters are the same either way.

Parameters

Name	Default	Meaning
`query`	required	The search string. Same syntax as the website - see query syntax.
`page`	1	1-based.
`per_page`	100	Up to your plan's row limit; `/v1/account` reports it as `max_per_page`.
`snippets`	off	`1` to include the matching text. Spends snippet quota.
`format`	`json`	One of six - see response formats.
`columns`	depends on format	Comma-separated subset of `domain`, `url`, `rank`, `ranked`, `snippets`.
`delimiter`	`;` / tab	For `csv` and `tsv`.
`header`	off	`1` to put a header line on `csv` and `tsv`.

GET

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

Remember to url-encode the query. Quotes, slashes and + all matter.

POST

The same parameters as a JSON body. Use it when the query is long or has several phrases: a multi-line query in a url runs into length limits in proxies and clients long before the server minds.

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

An array of phrases means all of them, exactly as separating them with newlines in the query string would. In the example above 278 sites carry the first phrase and 99 carry both.

JSON types are understood: true works where the query string needs 1. When a parameter is given in both the url and the body, the body wins.

The response

Field	Meaning
`total`	How many sites match, in the whole index. A real count, not an estimate.
`total_pages`	`total` divided by `per_page`, rounded up.
`returned`	How many rows this page actually carries.
`truncated`	Whether your plan's disclosed-position limit removed any of them.
`took_ms`	How long the search took, in milliseconds.
`results`	The rows.

A row

Field	Meaning
`domain`	The site.
`url`	The page the match was found on, which for `depth:` searches is not the home page.
`rank`	Position in the ranking, lower being more popular. `null` when the site has no rank.
`ranked`	`false` exactly when `rank` is `null`.
`snippets`	Only with `snippets=1`. Up to five `{"text", "match"}` pairs, where `match` is what matched and `text` is it with surrounding context.

Paging and bulk

Page through with page, or ask for everything at once with a large per_page - up to max_per_page from /v1/account, which on a paid plan is a million. There is no separate export endpoint; the answer is written out as it is built, so a million rows is not also a million rows held in memory somewhere.

Paging is cheap: repeating a query you have already run today is not charged again, so walking through pages costs one search rather than one per page. Snippet requests are the exception - those are charged every time. See quotas and rate limits.

Next Response formats