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 to launch an analysis on a project. GET to track its status.

# Launch an analysis
POST /api/v1/analyze.php
Body: { "project_id": 42, "question_type": "general" }

# Track the status
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

Optional parameters: 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).

# List webhooks
GET /api/v1/webhooks.php

# Create a webhook
POST /api/v1/webhooks.php
Body: { "action": "create", "name": "My webhook", "url": "https://...", "events": ["scan.completed"] }

# Test a webhook
POST /api/v1/webhooks.php
Body: { "action": "test", "webhook_id": 1 }
events: scan.completed | scan.failed | score.change
HMAC-SHA256 signature in the X-Geoptim-Signature header
POST GET /api/v1/reports.php - Automated reports

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

# Generate a report
POST /api/v1/reports.php
Body: {
  "project_id": 42,
  "format": "json",
  "include": ["scores", "recommendations", "history", "metrics"]
}

# Retrieve a report
GET /api/v1/reports.php?id=5

# List my reports
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