# Google Search Console API setup (free)

The Search Console API has **no usage billing** for normal site-owner queries. You need a free Google Cloud project and a service account — no credit card required for this API alone.

## 1. Google Cloud project

1. Open [Google Cloud Console](https://console.cloud.google.com/).
2. Create a **new project** (e.g. `artifis-seo`) — free tier is fine.

## 2. Enable the API

1. In the project, go to **APIs & Services → Library**.
2. Search for **Google Search Console API**.
3. Click **Enable**.

## 3. Service account + JSON key

1. **APIs & Services → Credentials → Create credentials → Service account**.
2. Name it (e.g. `seo-gsc-fetch`), finish creation.
3. Open the service account → **Keys → Add key → Create new key → JSON**.
4. Download the JSON file.
5. On the NAS, save it **outside git**:

   ```bash
   mkdir -p /volume1/web/secrets
   # copy gsc-sa.json to this path (scp from your PC — do not commit)
   chmod 600 /volume1/web/secrets/gsc-sa.json
   ```

6. Note the service account **email** (looks like `seo-gsc-fetch@….iam.gserviceaccount.com`).

## 4. Grant access in Search Console

1. Open [Google Search Console](https://search.google.com/search-console).
2. Select your property (`https://artifis.co.uk/` or domain property).
3. **Settings → Users and permissions → Add user**.
4. Paste the **service account email**.
5. Permission: **Owner** or **Full** (must be able to read performance data).

## 5. Environment variables on the server

Set these where PHP can read them (Synology Web Station PHP-FPM env, `web/seo/.env` loaded by your stack, or cron wrapper):

```bash
GSC_SERVICE_ACCOUNT_JSON=/volume1/web/secrets/gsc-sa.json
GSC_SITE_URL=https://artifis.co.uk/
GSC_AUTO_FETCH=1
```

- `GSC_SITE_URL` must match the property URL in Search Console exactly (including trailing slash for URL-prefix properties), or use `sc-domain:artifis.co.uk` for domain properties.
- `GSC_AUTO_FETCH=1` runs a fetch at the start of each **hourly** cron pass (optional).

See `.env.example` in this folder.

## 6. Test fetch

After the JSON is on the NAS and env vars are set:

```bash
# On NAS
php /volume1/web/seo/cron.php gsc

# Or via HTTP (if cron URL is reachable)
curl -fsS "https://YOUR-HOST/seo/cron.php?mode=gsc"
```

Check:

- `web/seo/logs/gsc_fetch.log`
- `web/seo/data/search_console_export.csv`
- [gsc_api.php](gsc_api.php) — should show **Connected** and row counts

## Troubleshooting

| Symptom | Fix |
|--------|-----|
| `JSON path … not readable` | Path wrong or permissions; `chmod 600`, owner readable by PHP user |
| `Google OAuth error` | Invalid or corrupt JSON key; re-download from Cloud Console |
| `User does not have sufficient permission` | Add service account email in Search Console with Owner/Full |
| `Site … not found` | `GSC_SITE_URL` must match property URL exactly |
| Empty CSV | Property has no query data in the last 28 days yet |

## Security

- **Never** commit `gsc-sa.json` or paste key contents into chat, git, or the dashboard.
- `.gitignore` excludes `**/gsc-sa.json` and `secrets/`.
- Rotate keys in Cloud Console if a key is ever exposed.