API Geoptim v1

Intégrez Geoptim dans vos outils

Accédez aux projets, scores et résultats d'analyse IA de vos clients directement via notre API REST. Intégrez la visibilité IA dans vos dashboards, rapports et workflows.

Se connecter Créer un compte

Documentation API

Intégration simple, réponses JSON standardisées

Authentification

Ajoutez votre token dans l'en-tête Authorization de chaque requête :

# Exemple cURL
curl -H "Authorization: Bearer ***token***" \
https://geoptim.ai/api/v1/projects.php
POST GET /api/v1/analyze.php - Lancer une analyse IA

POST pour lancer une analyse sur un projet. GET pour suivre son statut.

# Lancer une analyse
POST /api/v1/analyze.php
Body: { "project_id": 42, "question_type": "general" }

# Suivre le statut
GET /api/v1/analyze.php?id=123
project_id * question_type: general|ecommerce|local|saas
GET /api/v1/scores.php - Scores & métriques

Scores de visibilité IA, métriques détaillées et historique d'évolution.

GET /api/v1/scores.php?project_id=42
GET /api/v1/scores.php?project_id=42&last=1
GET /api/v1/scores.php?scan_id=123
project_id scan_id last=1 limit
GET /api/v1/recommendations.php - Recommandations IA

Recommandations personnalisées générées par l'IA, filtrables par priorité et catégorie.

GET /api/v1/recommendations.php?project_id=42
GET /api/v1/recommendations.php?scan_id=123&priority=critical
GET /api/v1/recommendations.php?scan_id=123&category=ai_visibility
project_id scan_id priority: critical|high|medium|low category: seo|content|technical|ai_visibility
GET /api/v1/projects.php - Liste tous vos projets

Paramètres optionnels : limit (max 100), offset, status (active/paused/archived)

GET /api/v1/projects.php?limit=10&offset=0
GET /api/v1/projects.php?id=42
GET /api/v1/scans.php - Scans et résultats

Récupérez les scans d'un projet ou l'intégralité des données d'un scan : volet GEO et volet SEO.

GET /api/v1/scans.php?project_id=42
GET /api/v1/scans.php?id=123
GET /api/v1/scans.php?audit_id=181
GET /api/v1/scans.php?id=123&include=seo_audit&seo_steps=step3_serp,step6_report
SectionContenu
analysisAnalyse canonique : blocs technique, performance, contenu, confiance et leurs preuves
geoQuestions, positions par IA, réponses brutes des IA, recommandations, query fan-out et SERP associées
trustAnalyse de confiance et plateformes d'avis
metricsMétriques mesurées pendant le scan
action_itemsActions recommandées et leur priorité
seo_auditAudit SEO de la page : Lighthouse et Core Web Vitals, on-page, maillage interne, mots-clés et positions, SERP, backlinks, E-E-A-T, content gaps, rapport
seo_domainScan SEO du domaine : cartographie, crawl, PageSpeed, mots-clés, marché
metadataMétadonnées brutes du pipeline (sur demande)
htmlHTML et Markdown capturés de la page (sur demande)
Paramètres : include (sections à livrer, all pour tout), exclude (sections à retirer), seo_steps (étapes de l'audit SEO). Sans paramètre, toutes les sections sauf metadata et html.
Positions des mots-clés : seo_audit.keyword_rankings donne pour chaque mot-clé la position moyenne retenue (position, rang dans la page Google) et chaque valeur observée (values). Un essai sans le site compte pour la première place hors du top 10 (counted_as).
GET /api/v1/competitors.php - Analyse concurrentielle

Comparez vos projets au benchmark global. Positionnement, percentile et déltas vs la moyenne.

GET /api/v1/competitors.php
GET /api/v1/competitors.php?project_id=42
Retourne : scores, benchmark global, percentile, vs_benchmark, vos autres projets
GET POST /api/v1/webhooks.php - Webhooks & alertes

Configurez des webhooks pour recevoir des notifications en temps réel (scan terminé, échec, variation de score).

# Lister les webhooks
GET /api/v1/webhooks.php

# Créer un webhook
POST /api/v1/webhooks.php
Body: { "action": "create", "name": "Mon webhook", "url": "https://...", "events": ["scan.completed"] }

# Tester un webhook
POST /api/v1/webhooks.php
Body: { "action": "test", "webhook_id": 1 }
events: scan.completed | scan.failed | score.change
Signature HMAC-SHA256 dans l'en-tête X-Geoptim-Signature
POST GET /api/v1/reports.php - Rapports automatisés

Générez des rapports complets au format JSON. Choisissez les sections à inclure : scores, recommandations, historique, métriques.

# Générer un rapport
POST /api/v1/reports.php
Body: {
  "project_id": 42,
  "format": "json",
  "include": ["scores", "recommendations", "history", "metrics"]
}

# Récupérer un rapport
GET /api/v1/reports.php?id=5

# Lister mes rapports
GET /api/v1/reports.php?list=1
sections: scores | recommendations | history | metrics | trust
GET /api/v1/stats.php - Statistiques globales

Vue synthétique : nb projets, scans, score moyen, top projets et évolution.

GET /api/v1/stats.php

Format de réponse

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2026-02-03T12:00:00+01:00",
    "api_version": "v1",
    "usage": {
      "daily_used": 42,
      "daily_limit": 5000,
      "daily_remaining": 4958
    }
  }
}

Codes HTTP

200
Succès
401
Non authentifié
429
Limite atteinte
404
Ressource introuvable