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 complete data from a scan: GEO panel and SEO panel.

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
SectionContent
analysisCanonical analysis: technical, performance, content, trust blocks and their evidence
geoQuestions, AI-positioned answers, raw AI responses, recommendations, query fan-out and associated SERPs
trustTrust analysis and review platforms
metricsMetrics measured during the scan
action_itemsRecommended actions and their priority
seo_auditPage SEO audit: Lighthouse and Core Web Vitals, on-page, internal linking, keywords and rankings, SERP, backlinks, E-E-A-T, content gaps, report
seo_domainDomain SEO scan: mapping, crawl, PageSpeed, keywords, market
metadataRaw pipeline metadata (on demand)
htmlHTML and Markdown captured from the page (on demand)
Parameters: include (sections to deliver, all for everything), exclude (sections to remove), seo_steps (SEO audit steps). Without parameters, all sections except metadata and html.
Keyword positions: seo_audit.keyword_rankings provides for each keyword the average retained position (position, rank on Google's page) and each observed value (values). A test without the site counts as the first position outside the top 10 (counted_as).
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