Search connections

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. 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`

curl https://api.usherstats.com/v1/sites \
  -H "Authorization: Bearer $US_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop", "hostnames": ["shop.example"]}'

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

curl https://api.usherstats.com/v1/sites/$SITE_ID/search \
  -H "Authorization: Bearer $US_TOKEN"

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":

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

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":

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

Bing

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

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.

curl "https://api.usherstats.com/v1/sites/$SITE_ID/search/weeks?weeks=26" \
  -H "Authorization: Bearer $US_TOKEN"

Disconnecting

The credentials are deleted; the weeks already collected stay.

curl -X DELETE https://api.usherstats.com/v1/sites/$SITE_ID/search/bing \
  -H "Authorization: Bearer $US_TOKEN"

Disconnecting a source that is not connected is 404:

curl -X DELETE https://api.usherstats.com/v1/sites/$SITE_ID/search/google \
  -H "Authorization: Bearer $US_TOKEN"