# Search connections

<!-- docs-test setup: owner -->

Google Search Console and Bing Webmaster Tools, connected with access you give and can take back; the setup on
Google's and Bing's side is in [Search Console and Bing](../search-console-and-bing.md). Credentials are checked,
encrypted, and used only by the daily pull of your site's own figures; no route shows a key again. Reading needs
`search:read`, connecting `search:write`.

| Route | Scope |
|---|---|
| `GET /v1/sites/{id}/search` | `search:read` |
| `PUT /v1/sites/{id}/search/google` | `search:write` |
| `PUT /v1/sites/{id}/search/bing` | `search:write` |
| `DELETE /v1/sites/{id}/search/google` | `search:write` |
| `DELETE /v1/sites/{id}/search/bing` | `search:write` |
| `GET /v1/sites/{id}/search/weeks` | `search:read` |

```sh
curl https://api.usherstats.com/v1/sites \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop", "hostnames": ["shop.example"]}'
```
<!-- expect 201; SITE_ID=.site.id -->

What is connected, and `serviceAccount`, the address to add to your Search Console property for delegated access:

```sh
curl https://api.usherstats.com/v1/sites/$SITE_ID/search \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

## Google

Delegated: add the `serviceAccount` address to the property (Restricted permission), then connect it. Delegated
access reads with UsherStats' own account, which every customer's property shares, so it is accepted only for a
property whose host is a **verified** hostname of the site (`sc-domain:shop.example` needs `shop.example`; a URL-prefix
property needs its own hostname). Before that, it is `400` with `"field": "property"`:

```sh
curl -X PUT https://api.usherstats.com/v1/sites/$SITE_ID/search/google \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "delegated", "property": "sc-domain:shop.example"}'
```
<!-- expect 400 -->

Or with your own service account: `"mode": "service_account"` and the key file's JSON as `"key"` (text or an
object). It reads only what you gave that account, so it needs no verified hostname. A file that is not a
service-account key is `400` with `"field": "key"`:

```sh
curl -X PUT https://api.usherstats.com/v1/sites/$SITE_ID/search/google \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "service_account", "property": "sc-domain:shop.example", "key": "{\"type\": \"authorized_user\"}"}'
```
<!-- expect 400 -->

## Bing

```sh
curl -X PUT https://api.usherstats.com/v1/sites/$SITE_ID/search/bing \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "your-bing-api-key", "siteUrl": "https://shop.example/"}'
```
<!-- expect 200 -->

## The figures

One row per week (starting Monday) and source: clicks, impressions, click-through rate, average position, how many
pages and queries were shown, and Bing's inbound links. The current week fills in day by day. A figure that could not
be collected is `null`; a zero is a measurement.

```sh
curl "https://api.usherstats.com/v1/sites/$SITE_ID/search/weeks?weeks=26" \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 200 -->

## Disconnecting

The credentials are deleted; the weeks already collected stay.

```sh
curl -X DELETE https://api.usherstats.com/v1/sites/$SITE_ID/search/bing \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 204 -->

Disconnecting a source that is not connected is `404`:

```sh
curl -X DELETE https://api.usherstats.com/v1/sites/$SITE_ID/search/google \
  -H "Authorization: Bearer $US_TOKEN"
```
<!-- expect 404 -->