Surfer API Verwendungsbeispiele

Hinweis: Diese Beispiele verwenden v1-Endpunkte. v1 funktioniert noch, ist aber veraltet. Wenn Sie eine neue Integration erstellen, verwenden Sie stattdessen die v2-Pfade unten:

V1 → V2-Endpunktzuordnung:

Was Sie tun	V1 (veraltet)	V2 (empfohlen)
Content Editor erstellen	`POST /api/v1/content_editors`	`POST /api/v2/workspaces/{workspace_id}/content_editors`
Content Editor-Status abrufen	`GET /api/v1/content_editors/{id}`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}`
Content Editor-Inhalt abrufen	`GET /api/v1/content_editors/{id}/content`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/content`
NLP-Begriffe abrufen	`GET /api/v1/content_editors/{id}/terms`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/seo_guidelines/terms`
Content Score abrufen	`GET /api/v1/content_editors/{id}/content_score`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/seo_guidelines/score`
Content Editors auflisten	`GET /api/v1/content_editors`	`GET /api/v2/content_editors` oder `GET /api/v2/workspaces/{workspace_id}/content_editors`
Arbeitsbereiche auflisten	`GET /api/v1/workspaces`	`GET /api/v2/workspaces`

SERP Analyzer, Audit, AI Detector und Humanizer bleiben auf V1 — V2-Äquivalente sind für diese Tools noch nicht verfügbar.

Hier sind ein paar Workflows, die von der Surfer-API-Integration über Ihre benutzerdefinierte App oder Lösungen von Drittanbietern wie Zapier oder Bubble.io profitieren können:

Erstellen mehrerer Abfragen und Freigeben von Zugriffslinks

Über die API können Sie die Erstellung von Abfragen für Content Editor, Audit und SERP Analyzer automatisieren. Basierend auf unseren Antworten können Sie dann Web-App-Zugriffslinks erstellen.

Sie könnten beispielsweise ein Google Sheet mit einer Liste von Keywords haben, für die Sie ranken möchten, und Sie möchten neue Artikel mit dem Content Editor erstellen.

In diesem Fall könnten Sie:

Formatieren Sie Ihr Tabellenblatt so, dass jede Zeile Ranking-Keywords und den Standort Ihres Zielmarkts enthält.
Extrahieren Sie für jede Zeile Keywords und Standortdaten und senden Sie diese mit einer POST Anfrage an den /api/v1/content_editors Endpunkt.
Tipp: Denken Sie daran, dass Keywords immer ein Array sein sollten, auch wenn Sie nur für ein Keyword optimieren möchten.
Als Antwort erhalten Sie:
```
{
"state": "scheduled",
"permalink_hash": "kKi7n3pkRk7Gw5cxKDiBAbCAybnDTt2z",
"id": 5632898
}
```
Sie können jetzt Abfrage-Zugriffslinks erstellen, indem Sie:
- "https://app.surferseo.com/drafts/" + "5632898" verbinden - dies ergibt einen privaten Link, auf den der Kontoinhaber oder ein Organisationsmitglied zugreifen kann
- "https://app.surferseo.com/drafts/s/" + "kKi7n3pkRk7Gw5cxKDiBA" verbinden, ergibt einen öffentlichen Freigabelink, auf den jeder zugreifen kann.
Teilen Sie diese mit Ihrem Team und externen Autoren, oder fügen Sie sie in das ursprüngliche Tabellenblatt ein, das Sie für die Keyword-Eingabe verwendet haben – je nachdem, was Ihr bevorzugter Arbeitsablauf erfordert.

Veröffentlichung von schriftlichen Inhalten in Ihrem CMS

Über die API können Sie eine saubere HTML-Version Ihres Content Editor-Entwurfs abrufen. Sie können diese dann über eine benutzerdefinierte Integration an Google Docs oder Ihr CMS senden.

Um Editor-Abfrageinhalte abzurufen, müssen Sie nur folgende Schritte ausführen:

Suchen Sie die "id" der Content Editor-Abfrage, von der Sie Inhalte herunterladen möchten.
Tipp: Falls Sie die ID für die Abfrage nirgendwo gespeichert haben, finden Sie diese einfach über die Web-App und kopieren Sie die letzte https://app.surferseo.com/drafts/5632898
Senden Sie eine GET Anfrage an /api/v1/content_editors/:id/content und geben Sie die gefundene "id" an, hier /api/v1/content_editors/5632898/content
Speichern Sie die Antwort.

Je nach Ziel-Texteditor/CMS müssen Sie möglicherweise das HTML, das wir bereitstellen, analysieren. Beispielsweise akzeptieren WordPress und Shopify Zeichenketten mit HTML-Tags als "Inhalt", daher ist keine Analyse oder Anpassung erforderlich.

Content Score für eine bestimmte URL abrufen

Mit Audit-Endpunkten können Sie den Content Score für die URL Ihrer Wahl und bis zu 5 Konkurrenten abrufen, die wir automatisch auswählen.

Gehen Sie dazu wie folgt vor:

Erstellen Sie eine neue Abfrage über eine POST Anfrage an den /api/v1/audits Endpunkt.

Speichern Sie die "id" aus unserer Antwort:

{
    "state": "scheduled",
    "id": 767429
}

Setzen Sie ein Zeitlimit von ein paar Minuten – bei einer schnell ladenden, geprüften Seite und regulärem Surfer-Traffic sollte es 5–10 Minuten dauern.
Senden Sie eine GET Anfrage mit dem /api/v1/audits/:id Endpunkt, hier /api/v1/audits/767429
Wenn "state" immer noch "scheduled" ist, führen Sie die GET Anfrage in ein paar Minuten erneut aus.

In der Antwort sollten Sie letztendlich folgendes erhalten:

{
"state": "completed",
"id": 482473,
"competitors_pages": [
{
"url": "https://www.competitor1.com/",
"content_score": 64
},
{
"url": "https://www.competitor2.com/",
"content_score": 49
},
{
"url": "https://www.competitor3.com/",
"content_score": 55
},
{
"url": "https://www.competitor4.com/",
"content_score": 78
},
{
"url": "https://www.competitor5.com/",
"content_score": 48
}
],
"audited_page": {
"url": "https://www.auditedURL.com/",
"content_score": 81
}
}

Der Content Score der geprüften URL ist unter audited_page.content_score verfügbar.

KI-Inhalte in einem Text erkennen

Verwenden Sie den AI Detector-Endpunkt, um die Wahrscheinlichkeit zu schätzen, dass ein bestimmter Text von KI generiert wurde. Er gibt eine Gesamtwahrscheinlichkeit, das verwendete Modell und optionale Details pro Chunk zurück.

Beispiel cURL:

curl -X POST "https://app.surferseo.com/api/v1/ai_detector/detect" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -d '{
        "text": "Paste or load up to 100k characters here.",
        "max_chunk_size": 8190,
        "model": "surfer-ai-detector-v2",
        "semantic_chunking": true
      }'

Beispielantwort:

{
  "model": "surfer-ai-detector-v2",
  "ai_probability": 0.82,
  "chunks": [
    { "start": 0, "end": 1200, "probability": 0.76 },
    { "start": 1201, "end": 2400, "probability": 0.88 }
  ]
}

Eingabe: text (≤100.000 Zeichen). Optional: max_chunk_size, model (surfer-ai-detector-v1 oder -v2), semantic_chunking (Standard true).
Fehler, die möglicherweise angezeigt werden: 422 Quota exceeded | No access, 429 Rate limit exceeded.
Ratenlimit (Endpunkt): 60 Anfragen/Min.

Text humanisieren (Umformulierung für natürlichere Lesbarkeit)

Verwenden Sie den Humanizer-Endpunkt, um längere Passagen so umzuschreiben, dass sie menschlicher wirken und gleichzeitig die Bedeutung bewahrt bleibt.

Beispiel cURL:

curl -X POST "https://app.surferseo.com/api/v1/humanizer/humanize" \
  -H "Content-Type: application/json" \
  -H "API-KEY: YOUR_API_KEY" \
  -d '{
        "text": "Provide 128+ characters you want to humanize.",
        "model": "surfer-humanizer-v1",
        "stream": false
      }'

Beispielantwort:

{
  "model": "surfer-humanizer-v1",
  "text": "Here's the rewritten version that keeps your meaning but reads more naturally."
}

Eingabe: text (≥128 Zeichen); model: surfer-humanizer-v1; optional stream für segmentierte Ausgabe.
Häufiger Fehler: 422 Quota exceeded | No access.

Daten über SERP-Konkurrenten für Ihre SEO-Analyse sammeln

Wenn Sie statistische Daten über Konkurrenten von Google abrufen oder eine Liste der von uns entdeckten prominenten Begriffe exportieren möchten, können Sie diese Endpunkte nutzen:

/api/v1/exports/csv/serp_analyzer/:id/search_results
/api/v1/exports/csv/serp_analyzer/:id/prominent_terms Endpunkte.

Dazu können Sie:

Erstellen Sie SERP Analyzer-Abfragen für Keywords, die Sie analysieren möchten, indem Sie eine POST Anfrage an die Endpunkte /api/v1/serp_analyzer oder /api/v1/serp_analyzer/batches senden.
Speichern Sie den Wert "id" aus der Antwort für jede Abfrage, die Sie interessiert.
```
{
"state": "scheduled",
"id": 2800997
}
```
Setzen Sie ein Timeout von ein paar Minuten – bei normalem Surfer-Verkehr sollte eine Abfrage 5–10 Minuten dauern.
Wenn Sie mehr als 10 Abfragen gleichzeitig oder in kurzer Abfolge ausgeführt haben, können diese aufgrund des Load-Balancing auf unserer Seite langsamer abgeschlossen werden.
Sie können jetzt GET Anfragen ausführen:
- an den Endpunkt /api/v1/exports/csv/serp_analyzer/2800997/search_results, um eine Liste der SERP-Konkurrenten und numerische Daten zu ihren platzierten URLs zu erhalten, einschließlich Content Score
- an den Endpunkt /api/v1/exports/csv/serp_analyzer/2800997/prominent_terms, um eine Liste der prominenten Begriffe zu erhalten, die wir in den SERP-Ergebnissen gefunden haben.

Bitte beachten Sie, dass diese Ergebnisse „Rohdaten" sind und nicht dem entsprechen, was Sie als Richtlinien im Content Editor oder in der Audit-Funktion sehen würden, die zusätzliche Verarbeitung erhalten.

Zusätzliche Ressourcen:

Surfer API Einführung

Surfer API Dokumentation

Surfer API Fehlerbehebung

Help center

Help center

Surfer API Verwendungsbeispiele

Ein paar Beispiele unserer API in Aktion!

V1 → V2-Endpunktzuordnung:

Erstellen mehrerer Abfragen und Freigeben von Zugriffslinks

Veröffentlichung von schriftlichen Inhalten in Ihrem CMS

Content Score für eine bestimmte URL abrufen

KI-Inhalte in einem Text erkennen

Text humanisieren (Umformulierung für natürlichere Lesbarkeit)

Daten über SERP-Konkurrenten für Ihre SEO-Analyse sammeln

Zusätzliche Ressourcen:

Help center

Help center

Surfer API Verwendungsbeispiele

Ein paar Beispiele unserer API in Aktion!

V1 → V2-Endpunktzuordnung:

Erstellen mehrerer Abfragen und Freigeben von Zugriffslinks

Veröffentlichung von schriftlichen Inhalten in Ihrem CMS

Content Score für eine bestimmte URL abrufen

KI-Inhalte in einem Text erkennen

Text humanisieren (Umformulierung für natürlichere Lesbarkeit)

​Daten über SERP-Konkurrenten für Ihre SEO-Analyse sammeln

Zusätzliche Ressourcen:

Daten über SERP-Konkurrenten für Ihre SEO-Analyse sammeln