API-Referenz

Basis-URL & Format

https://tool.search-console.pro/api/v1

Alle Antworten sind JSON, auch Fehler. Listen kommen im Format {"data":[…],"meta":{…}}, Einzelobjekte als {"data":{…}}. Zeitangaben folgen ISO 8601.

Unterstützt werden GET, HEAD und OPTIONS. Schreibende Verfahren beantwortet die API mit 405.

Authentifizierung

Jede Anfrage braucht einen API-Key im Header. Zwei Schreibweisen sind möglich:

Authorization: Bearer DEIN_API_KEY

X-API-Key: DEIN_API_KEY

Der Schlüssel wird bewusst nicht als Query-Parameter akzeptiert – Schlüssel in URLs landen in Server-Logs, Proxys und Browser-Verläufen.

Schlüssel anlegen

1. In der Anwendung auf „Einstellungen" → „API-Zugang"
2. Name vergeben und Berechtigungen auswählen
3. Schlüssel erzeugen und sofort kopieren – er wird nur einmal angezeigt

Lege pro Anwendung einen eigenen Schlüssel an. Geht einer verloren, löschst du genau diesen, ohne alles andere lahmzulegen.

Berechtigungen

Jeder Schlüssel trägt eine Menge von Geltungsbereichen. Fehlt der passende, antwortet die API mit 403 insufficient_scope.

Ältere Schlüssel ohne hinterlegte Auswahl haben alle Lesebereiche.

Endpunkte

GET /properties

Alle Properties des Schlüsselinhabers. Benötigt properties:read.

{
  "data": [
    {
      "id": 12,
      "site_url": "https://example.de/",
      "display_name": "Example",
      "permission_level": "siteOwner",
      "is_active": true,
      "last_sync": "2026-08-02T04:00:00+00:00",
      "created_at": "2025-11-14T10:22:00+00:00"
    }
  ],
  "meta": { "count": 1 }
}

GET /properties/{id}

Eine einzelne Property. Benötigt properties:read.

GET /properties/{id}/performance

Performance-Daten. Benötigt performance:read.

{
  "data": [
    { "key": "2026-07-05", "clicks": 128, "impressions": 4210, "ctr": 3.04, "position": 12.7 }
  ],
  "meta": {
    "property_id": 12, "dimension": "date",
    "start": "2026-07-05", "end": "2026-08-01",
    "limit": 100, "offset": 0, "count": 28
  }
}

GET /properties/{id}/keywords

Beobachtete Keywords mit der jeweils jüngsten Position. Benötigt keywords:read. Parameter: limit, offset.

GET /properties/{id}/sci

Verlauf des Search Console Index. Benötigt sci:read. Parameter: limit (1–365, Standard 30).

{
  "data": [
    { "date": "2026-08-01", "score": 31.4, "components": { "impressions": 61.2, "clicks": 19.1 } }
  ],
  "meta": { "property_id": 12, "count": 30 }
}

GET /crawls

Crawls auflisten. Benötigt crawls:read. Parameter: property_id, limit (1–200, Standard 50), offset.

GET /crawls/{id}

Ein Crawl inklusive der nach Typ gruppierten Probleme. Benötigt crawls:read.

{
  "data": {
    "id": 481, "property_id": 12,
    "status": "completed", "pages_crawled": 1284,
    "errors_found": 7, "warnings_found": 35,
    "scores": { "overall": 78.0, "seo": 82.0, "content": 74.0, "technical": 77.0 },
    "issues": [
      { "type": "missing_h1", "title": "H1 fehlt", "severity": "critical", "category": "seo", "count": 3 }
    ]
  }
}

Fehler

Fehler kommen immer in derselben Form:

{ "error": { "code": "invalid_key", "message": "Der API-Key ist ungültig oder wurde deaktiviert." } }

Fremde IDs beantworten wir mit 404 statt 403. Sonst ließe sich durch Ausprobieren herausfinden, welche IDs existieren.

Begrenzung

120 Anfragen pro Minute je Schlüssel. Jede Antwort trägt:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1785000060

Bei Überschreitung kommt 429 mit einem Retry-After-Header.

OpenAPI

Die vollständige Schnittstellenbeschreibung nach OpenAPI 3.1:

https://tool.search-console.pro/api/v1/openapi.json

Damit lassen sich Clients generieren oder die API direkt in Postman und Insomnia laden. Ein GET auf /api/v1 liefert außerdem eine kurze Selbstauskunft mit allen Endpunkten.

Beispiele

cURL

curl -H "Authorization: Bearer $SCP_KEY" \
  "https://tool.search-console.pro/api/v1/properties"

curl -H "Authorization: Bearer $SCP_KEY" \
  "https://tool.search-console.pro/api/v1/properties/12/performance?dimension=query&limit=25"

Python

import os, requests

BASE = "https://tool.search-console.pro/api/v1"
headers = {"Authorization": f"Bearer {os.environ['SCP_KEY']}"}

r = requests.get(f"{BASE}/properties", headers=headers, timeout=30)
r.raise_for_status()

for p in r.json()["data"]:
    print(p["id"], p["site_url"])

PHP

$ch = curl_init('https://tool.search-console.pro/api/v1/properties');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('SCP_KEY')],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($response['data'] as $property) {
    echo $property['id'] . ' ' . $property['site_url'] . PHP_EOL;
}

JavaScript

const BASE = 'https://tool.search-console.pro/api/v1';

const res = await fetch(`${BASE}/properties`, {
  headers: { Authorization: `Bearer ${process.env.SCP_KEY}` }
});
if (!res.ok) throw new Error((await res.json()).error.message);

const { data } = await res.json();
data.forEach(p => console.log(p.id, p.site_url));