Geoptim API v1

Intégrez Geoptim dans your tools

Access your clients' projects, scores and AI analysis results directly through our REST API. Integrate AI visibility into your dashboards, reports and workflows.

Log in Create an Account

API Documentation

Simple integration, standardized JSON responses

Authentication

Add your token in the Authorization header of each request:

# cURL Example
curl -H "Authorization: Bearer ***token***" \
https://geoptim.ai/api/v1/projects.php
POST GET /api/v1/analyze.php - Launch an AI analysis

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 & metrics

AI visibility scores, detailed metrics and evolution history.

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 - AI Recommendations

AI-generated personalized recommendations, filterable by priority and category.

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 - Lists all your projects

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 and results

Retrieve scans from a project or the complete details of a specific scan.

GET /api/v1/scans.php?project_id=42
GET /api/v1/scans.php?id=123
GET /api/v1/competitors.php - Competitor analysis

Compare your projects against the global benchmark. Positioning, percentile and deltas vs. average.

GET /api/v1/competitors.php
GET /api/v1/competitors.php?project_id=42
Returns: scores, global benchmark, percentile, vs_benchmark, your other projects
GET POST /api/v1/webhooks.php - Webhooks & alerts

Set up webhooks to receive real-time notifications (scan completed, failure, score variation).

# 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 - Automated reports

Generate comprehensive reports in JSON format. Choose sections to include: scores, recommendations, history, metrics.

# 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 - Global statistics

Synthetic view: number of projects, scans, average score, top projects and evolution.

GET /api/v1/stats.php

Response format

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

HTTP Codes

200
Success
401
Not authenticated
429
Limit reached
404
Resource not found