v1.0.0
Documentation

API REST OSINT

Recherchez des informations publiques sur une personne à partir de critères simples. L'API génère automatiquement des dizaines de requêtes optimisées, interroge SearXNG, déduplique les résultats et attribue un score de pertinence à chaque entrée.

Recherche stratégique

Génération automatique de requêtes multi-sources optimisées.

Scoring intelligent

Score de pertinence 0–100 basé sur la correspondance des critères.

Déduplication

Fusion des doublons avec cumul du score de pertinence.

Rate limiting

100 requêtes/heure par clé API, configurable.

L'API est hébergée sur :

Base URL
http://100.80.6.13:8000

Authentification

Chaque requête doit inclure une clé API valide. Deux méthodes sont acceptées :

Via le header X-API-Key

Header
X-API-Key: votre_cle_api

Via Authorization Bearer

Header
Authorization: Bearer votre_cle_api
i

Contactez l'administrateur pour obtenir votre clé API. Chaque clé est associée à un propriétaire et à un rate limit configurable.


Endpoints

L'API expose deux endpoints publics.

GET /health Vérifier l'état de l'API
POST /search Lancer une recherche OSINT

Health check

Permet de vérifier que l'API est opérationnelle. Aucune authentification requise.

GET /health
curl http://100.80.6.13:8000/health
import requests

response = requests.get("http://100.80.6.13:8000/health")
print(response.json())
const response = await fetch("http://100.80.6.13:8000/health")
const data = await response.json()
console.log(data)
200 OK
{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00.000000",
  "version": "1.0.0"
}


Paramètres de recherche

Le corps de la requête doit être en JSON (Content-Type: application/json).

Champ Type Requis Description
prenom string optionnel Prénom de la personne (max 100 car.)
nom string optionnel Nom de famille (max 100 car.)
telephone string optionnel Numéro de téléphone (max 20 car.)
email string optionnel Adresse email (max 254 car.)
adresse string optionnel Adresse postale (max 255 car.)
ville string optionnel Ville (max 100 car.)
code_postal string optionnel Code postal (max 10 car.)
pays string optionnel Pays (ex : France)
max_results integer optionnel Nombre max de résultats. Min 1, max 200. Défaut : 100
+

Plus vous fournissez de critères, plus les résultats seront pertinents et le score de correspondance élevé.


Format de réponse

200 OK — application/json
{
  "success": true,
  "total_results": 23,
  "queries_generated": 18,
  "processing_time_seconds": 4.231,
  "results": [
    {
      "score": 87.5,
      "url": "https://www.linkedin.com/in/jean-dupont-75",
      "title": "Jean Dupont - Ingénieur | LinkedIn",
      "description": "Jean Dupont | 500+ relations | Paris...",
      "engine": "google",
      "matched_queries_count": 3,
      "matched_fields": ["nom_prenom", "email"],
      "queries": ["site:linkedin.com \"Jean Dupont\""]
    }
  ]
}

Champs de la réponse

ChampTypeDescription
success boolean Indique si la requête a abouti
total_results integer Nombre total de résultats retournés
queries_generated integer Nombre de requêtes SearXNG générées
processing_time_seconds float Durée totale de traitement en secondes
results[].score float Score de pertinence entre 0 et 100
results[].url string URL du résultat
results[].matched_fields array Critères ayant déclenché ce résultat
results[].queries array Requêtes SearXNG ayant retourné ce résultat

Rate Limiting

Chaque clé API est limitée à 100 requêtes par heure par défaut. Cette limite est configurable par clé.

En cas de dépassement, l'API retourne immédiatement une erreur 429.

429 Too Many Requests
{
  "success": false,
  "error": "Rate limit exceeded. Retry in 1 hour.",
  "status_code": 429
}

Codes d'erreur

L'API retourne des réponses JSON structurées pour toutes les erreurs.

Code HTTPDescription
401 Clé API manquante ou invalide
403 Clé désactivée ou expirée
422 Paramètres invalides ou manquants (aucun critère fourni)
429 Rate limit dépassé — réessayer dans 1 heure
500 Erreur interne du serveur

Format d'erreur

4xx / 5xx Error
{
  "success": false,
  "error": "Message d'erreur descriptif",
  "status_code": 401
}

Exemples Python

Installation

Terminal
pip install requests

Recherche minimale

search_basic.py
import requests

API_URL = "http://100.80.6.13:8000"
API_KEY = "votre_cle_api"

response = requests.post(
    f"{API_URL}/search",
    headers={"X-API-Key": API_KEY},
    json={
        "prenom": "Jean",
        "nom": "Dupont"
    }
)

data = response.json()
print(f"Résultats trouvés : {data['total_results']}")

for result in data["results"]:
    print(f"  [{result['score']:.1f}] {result['url']}")

Recherche complète avec gestion d'erreurs

search_advanced.py
import requests
from requests.exceptions import RequestException

class OsintClient:
    def __init__(self, api_key: str, base_url: str = "http://100.80.6.13:8000"):
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({"X-API-Key": api_key})

    def search(self, **criteria) -> dict:
        try:
            r = self.session.post(
                f"{self.base_url}/search",
                json=criteria,
                timeout=30
            )
            r.raise_for_status()
            return r.json()
        except requests.HTTPError as e:
            err = e.response.json().get("error", str(e))
            raise ValueError(f"API error {e.response.status_code}: {err}")

# Utilisation
client = OsintClient("votre_cle_api")

results = client.search(
    prenom="Jean",
    nom="Dupont",
    email="jean.dupont@example.com",
    ville="Paris",
    pays="France",
    max_results=50
)

print(f"✓ {results['total_results']} résultats en {results['processing_time_seconds']:.2f}s")

for r in results["results"][:5]:  # Top 5
    print(f"  [{r['score']:5.1f}] {r['title']}")
    print(f"         {r['url']}")

Exemples Node.js

Avec fetch natif (Node 18+)

search.mjs
const API_URL = "http://100.80.6.13:8000"
const API_KEY = "votre_cle_api"

const searchOsint = async (criteria) => {
  const response = await fetch(`${API_URL}/search`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY
    },
    body: JSON.stringify(criteria)
  })

  if (!response.ok) {
    const err = await response.json()
    throw new Error(`API ${response.status}: ${err.error}`)
  }

  return response.json()
}

// Exemple d'utilisation
const results = await searchOsint({
  prenom: "Jean",
  nom: "Dupont",
  email: "jean.dupont@example.com",
  ville: "Paris",
  max_results: 50
})

console.log(`✓ ${results.total_results} résultats`)
results.results.slice(0, 5).forEach((r) => {
  console.log(`  [${r.score.toFixed(1)}] ${r.url}`)
})

Classe client TypeScript

osint-client.ts
interface SearchCriteria {
  prenom?: string
  nom?: string
  telephone?: string
  email?: string
  adresse?: string
  ville?: string
  code_postal?: string
  pays?: string
  max_results?: number
}

interface SearchResult {
  score: number
  url: string
  title: string
  description: string
  engine: string
  matched_queries_count: number
  matched_fields: string[]
  queries: string[]
}

interface SearchResponse {
  success: boolean
  total_results: number
  queries_generated: number
  processing_time_seconds: number
  results: SearchResult[]
}

class OsintClient {
  private baseUrl: string
  private apiKey: string

  constructor(apiKey: string, baseUrl = "http://100.80.6.13:8000") {
    this.apiKey = apiKey
    this.baseUrl = baseUrl
  }

  async search(criteria: SearchCriteria): Promise<SearchResponse> {
    const res = await fetch(`${this.baseUrl}/search`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": this.apiKey
      },
      body: JSON.stringify(criteria)
    })

    const json = await res.json()
    if (!res.ok) throw new Error(json.error)
    return json
  }

  async health(): Promise<boolean> {
    const res = await fetch(`${this.baseUrl}/health`)
    return res.ok
  }
}

// Usage
const client = new OsintClient("votre_cle_api")
const data = await client.search({ prenom: "Jean", nom: "Dupont" })