# 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](https://publicwww.com/docs/query-syntax/). |
| `page` | 1 | 1-based. |
| `per_page` | 100 | Up to your plan's row limit, and so is `page × per_page`: a plan covers the first N rows of a query, paging does not go past them (`400 page_too_deep`); `/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](https://publicwww.com/docs/api/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.

Source: https://publicwww.com/docs/api/requests/