Exemples d'utilisation de l'API Surfer

Attention : ces exemples utilisent les endpoints v1. La v1 fonctionne toujours, mais elle est obsolète. Si vous créez une nouvelle intégration, utilisez plutôt les chemins v2 ci-dessous :

Correspondance des endpoints V1 → V2 :

Ce que vous faites	V1 (obsolète)	V2 (recommandé)
Créer un Content Editor	`POST /api/v1/content_editors`	`POST /api/v2/workspaces/{workspace_id}/content_editors`
Obtenir le statut d'un Content Editor	`GET /api/v1/content_editors/{id}`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}`
Obtenir le contenu d'un Content Editor	`GET /api/v1/content_editors/{id}/content`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/content`
Obtenir les termes NLP	`GET /api/v1/content_editors/{id}/terms`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/seo_guidelines/terms`
Obtenir le Content Score	`GET /api/v1/content_editors/{id}/content_score`	`GET /api/v2/workspaces/{workspace_id}/content_editors/{id}/seo_guidelines/score`
Lister les Content Editors	`GET /api/v1/content_editors`	`GET /api/v2/content_editors` ou `GET /api/v2/workspaces/{workspace_id}/content_editors`
Lister les espaces de travail	`GET /api/v1/workspaces`	`GET /api/v2/workspaces`

SERP Analyzer, Audit, AI Detector et Humanizer restent en V1 : les équivalents V2 ne sont pas encore disponibles pour ces outils.

Voici quelques flux de travail qui peuvent bénéficier de l'intégration de l'API Surfer via votre application personnalisée ou des solutions tierces comme Zapier ou Bubble.io :

Créer plusieurs requêtes et partager des liens d'accès

Via l'API, vous pouvez automatiser la création de requêtes pour Content Editor, Audit et SERP Analyzer. Ensuite, en fonction de nos réponses, vous pouvez créer des liens d'accès à l'application web.

Par exemple, vous pourriez avoir une Google Sheet avec une liste de mots-clés pour lesquels vous souhaitez vous positionner, et vous voulez créer de nouveaux articles en utilisant Content Editor.

Dans ce cas, vous pourriez :

Structurez votre feuille pour que chaque ligne contienne les mots-clés à cibler et la localisation de votre audience cible.
Pour chaque ligne, extrayez les mots-clés et les données de localisation et envoyez-les à l'aide d'une requête POST vers l’endpoint /api/v1/content_editors.
Conseil : N'oubliez pas que les mots-clés doivent toujours être un tableau, même si vous n'optimisez que pour un seul mot-clé.
En réponse, vous recevrez :
```
{
"state": "scheduled",
"permalink_hash": "kKi7n3pkRk7Gw5cxKDiBAbCAybnDTt2z",
"id": 5632898
}
```
Vous pouvez maintenant créer des liens d'accès aux requêtes en :
- joignant "https://app.surferseo.com/drafts/" + « 5632898 » : cela crée un lien privé que le propriétaire du compte ou un membre de l'organisation peut consulter
- joignant "https://app.surferseo.com/drafts/s/" + "kKi7n3pkRk7Gw5cxKDiBA" créera un lien de partage public accessible à tous.
Partagez-les avec votre équipe et les rédacteurs externes, ou collez-les dans la feuille d'origine que vous avez utilisée pour la saisie des mots-clés : selon le flux de travail que vous préférez.

Publier du contenu écrit sur votre CMS

Via l'API, vous pouvez obtenir une version HTML propre de votre brouillon Content Editor. Vous pouvez ensuite l'envoyer à Google Docs ou à votre CMS via une intégration personnalisée.

Pour obtenir le contenu de la requête Editor, il vous suffit de :

Repérez l'« id » de la requête Content Editor à partir de laquelle vous souhaitez télécharger du contenu.
Conseil : Si vous n'avez pas stocké l'ID de la requête quelque part, trouvez-le simplement via l'application web et copiez le dernier https://app.surferseo.com/drafts/5632898
Envoyez une requête GET à /api/v1/content_editors/:id/content en spécifiant l'"id" que vous avez trouvé, ici /api/v1/content_editors/5632898/content
Stockez la réponse.

Selon votre éditeur de texte/CMS cible, vous devrez peut-être analyser le HTML que nous fournissons. Par exemple, Wordpress et Shopify acceptent les chaînes avec des balises HTML en tant que « contenu », donc aucune analyse/ajustement n'est nécessaire.

Obtenir le Content Score pour une URL spécifique

À l'aide des endpoints Audit, vous pouvez obtenir le Content Score de l'URL que vous choisissez et de jusqu'à 5 concurrents que nous sélectionnons automatiquement.

Pour ce faire :

Créez une nouvelle requête via POST vers l’endpoint /api/v1/audits.

Stockez l'"id" de notre réponse :

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

Prévoyez un délai de quelques minutes : avec une page auditée à chargement rapide et une requête de trafic Surfer régulier, cela devrait prendre 5 à 10 minutes.
Envoyez une requête GET en utilisant l’endpoint /api/v1/audits/:id, ici /api/v1/audits/767429
Si l'"state" est toujours "scheduled," relancez la requête GET à nouveau dans quelques minutes.

En réponse, vous devriez finalement obtenir :

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

Le Content Score de l'URL auditée est disponible sous audited_page.content_score.

Détecter le contenu généré par l'IA dans un texte

Utilisez l’endpoint AI Detector pour estimer la probabilité qu'un texte donné ait été généré par l'IA. il renvoie une probabilité globale, le modèle utilisé et, en option, des détails par segment (chunk).

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

Exemple de réponse :

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

Entrée : text (≤100 000 caractères). Optionnel : max_chunk_size, model (surfer-ai-detector-v1 ou -v2), semantic_chunking (par défaut true).
Erreurs possibles : 422 Quota exceeded | No access, 429 Rate limit exceeded.
Limite de débit (endpoint) : 60 requêtes/min.

Humaniser le texte (paraphraser pour un ton plus naturel)

Utilisez l'endpoint Humanizer pour réécrire des passages plus longs afin qu'ils paraissent plus naturels tout en préservant le sens.

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

Exemple de réponse :

{
  "model": "surfer-humanizer-v1",
  "text": "Voici la version réécrite qui conserve votre sens mais se lit plus naturellement."
}

Entrée : text (≥128 caractères) ; model : surfer-humanizer-v1 ; stream optionnel pour une sortie fragmentée.
Erreur courante : 422 Quota exceeded | No access.

Collecter des données sur les concurrents SERP pour votre analyse SEO

Si vous souhaitez obtenir des données statistiques sur les concurrents de Google ou exporter une liste des termes importants que nous avons découverts, vous pouvez utiliser ces endpoints :

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

Pour ce faire, vous pouvez :

Créez des requêtes SERP Analyzer pour les mots-clés que vous souhaitez analyser en utilisant une requête POST vers les endpoints /api/v1/serp_analyzer ou /api/v1/serp_analyzer/batches.
Conservez la valeur "id" de la réponse pour chaque requête qui vous intéresse.
```
{
"state": "scheduled",
"id": 2800997
}
```
Prévoyez un délai de quelques minutes : avec le trafic Surfer habituel, une requête devrait prendre 5 à 10 minutes.
Si vous avez lancé plus de 10 requêtes à la fois ou en succession rapide, elles pourraient se terminer plus lentement en raison de l'équilibrage de charge effectué de notre côté.
Vous pouvez maintenant exécuter des requêtes GET :
- vers l’endpoint /api/v1/exports/csv/serp_analyzer/2800997/search_results pour obtenir une liste des concurrents SERP et des données chiffrées sur leurs URL positionnées, y compris le Content Score
- vers l’endpoint /api/v1/exports/csv/serp_analyzer/2800997/prominent_terms pour obtenir une liste des termes importants que nous avons découverts dans les résultats SERP.

Veuillez noter que ces résultats sont des « données brutes » et ne correspondent pas aux Directives affichées dans le Content Editor ou l'Audit, qui font l'objet d'un traitement supplémentaire.

Ressources supplémentaires :

Introduction à l'API Surfer

Documentation de l'API Surfer

Dépannage de l'API Surfer

Help center

Help center

Exemples d'utilisation de l'API Surfer

Quelques exemples de notre API en action !

Correspondance des endpoints V1 → V2 :

Créer plusieurs requêtes et partager des liens d'accès

Publier du contenu écrit sur votre CMS

Obtenir le Content Score pour une URL spécifique

Détecter le contenu généré par l'IA dans un texte

Humaniser le texte (paraphraser pour un ton plus naturel)

Collecter des données sur les concurrents SERP pour votre analyse SEO

Ressources supplémentaires :

Help center

Help center

Exemples d'utilisation de l'API Surfer

Quelques exemples de notre API en action !

Correspondance des endpoints V1 → V2 :

Créer plusieurs requêtes et partager des liens d'accès

Publier du contenu écrit sur votre CMS

Obtenir le Content Score pour une URL spécifique

Détecter le contenu généré par l'IA dans un texte

Humaniser le texte (paraphraser pour un ton plus naturel)

​Collecter des données sur les concurrents SERP pour votre analyse SEO

Ressources supplémentaires :

Collecter des données sur les concurrents SERP pour votre analyse SEO