> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taap.it/llms.txt
> Use this file to discover all available pages before exploring further.

# API Radar

> Lisez vos analyses Radar (Visitors) par programmation avec une clé API liée à un projet

L'**API Radar** permet à des applications externes de lire les analyses collectées par Taapit
Radar (le produit Visitors) : métriques agrégées, séries temporelles, visiteurs en temps réel
et principaux regroupements (pages, sources, localisations, appareils).

## URL de base

```
https://taap.it/api/v1/radar
```

## Authentification

Les endpoints Radar sont authentifiés avec une **clé API liée à un projet**. Chaque clé
appartient à un seul projet Radar (un site web) : vous ne transmettez donc jamais de
`projectId`, le projet est déduit de la clé elle-même.

Envoyez la clé sous forme de jeton Bearer :

```http theme={null}
Authorization: Bearer taapit_votre_cle_api_ici
```

Vous pouvez aussi utiliser l'en-tête `x-api-key` :

```http theme={null}
x-api-key: taapit_votre_cle_api_ici
```

<Info>
  Les clés API se créent depuis le tableau de bord Radar, dans **Paramètres du projet → API**.
  La clé complète n'est affichée qu'une seule fois à la création : conservez-la en lieu sûr et ne
  l'exposez jamais côté client.
</Info>

### Permissions

Chaque clé porte un niveau de permission (**Toutes**, **Lecture seulement** ou **Restreintes**).
Tous les endpoints Radar actuels sont en lecture seule : n'importe quel niveau de permission
peut donc les appeler. Les portées d'écriture sont réservées à de futurs endpoints.

## Endpoints

<CardGroup cols={2}>
  <Card title="Métriques" icon="chart-simple" href="/fr/api-reference/radar/metrics">
    Métriques agrégées sur une plage de dates (visiteurs, visites, pages vues, revenus…).
  </Card>

  <Card title="Séries temporelles" icon="chart-line" href="/fr/api-reference/radar/timeseries">
    Séries des métriques principales réparties dans le temps.
  </Card>

  <Card title="Temps réel" icon="signal-stream" href="/fr/api-reference/radar/realtime">
    Visiteurs actifs sur une fenêtre glissante.
  </Card>

  <Card title="Regroupements" icon="layer-group" href="/fr/api-reference/radar/breakdowns">
    Principales pages, sources, localisations et appareils.
  </Card>

  <Card title="Personnes" icon="users" href="/fr/api-reference/radar/people">
    Liste des personnes (visiteurs) avec leurs attributs clés et des filtres.
  </Card>

  <Card title="Détails d'une personne" icon="user" href="/fr/api-reference/radar/people-details">
    Une personne avec ses sessions et sa heatmap d'activité.
  </Card>

  <Card title="Derniers visiteurs" icon="bolt" href="/fr/api-reference/radar/last-visitors">
    Visiteurs actifs dans les dernières minutes (flux en direct).
  </Card>

  <Card title="Événements personnalisés" icon="bullseye" href="/fr/api-reference/radar/custom-events">
    Événements personnalisés les plus fréquents du projet.
  </Card>
</CardGroup>

## Paramètres de date

Les endpoints qui acceptent une plage de dates utilisent les paramètres de requête `start` et
`end` au format ISO 8601 (UTC), par exemple `2026-01-01T00:00:00Z`.

## Limites de débit & quotas

Les endpoints Radar s'appuient sur un moteur d'analyse facturé à la requête : chaque clé API
possède donc des **limites de débit par clé** pour maîtriser l'usage (et vos coûts) :

| Fenêtre | Limite par défaut      |
| ------- | ---------------------- |
| Seconde | 3 requêtes / seconde   |
| Minute  | 60 requêtes / minute   |
| Jour    | 5 000 requêtes / jour  |
| Mois    | 50 000 requêtes / mois |

Le plafond par seconde est un **garde-fou anti-burst** : une clé ne peut jamais dépasser quelques
requêtes par seconde, ce qui maintient l'usage bien en dessous du seuil de facturation par
seconde du moteur d'analyse.

Chaque réponse inclut des en-têtes de limite de débit pour suivre votre budget restant :

```http theme={null}
X-RateLimit-Limit: 5000        # limite quotidienne
X-RateLimit-Remaining: 4987    # requêtes restantes aujourd'hui
X-RateLimit-Reset: 1769990400  # epoch UTC (s) de réinitialisation de la fenêtre journalière
```

Lorsqu'une limite est dépassée, l'API renvoie **`429 Too Many Requests`** avec un en-tête
`Retry-After` (secondes à attendre) et un champ `scope` indiquant la fenêtre atteinte
(`second`, `minute`, `day` ou `month`).

<Warning>
  L'usage est journalisé **par clé et par endpoint**. Les endpoints de type flux comme `realtime`
  et `last-visitors` consomment du quota à chaque appel : mettez les réponses en cache et évitez un
  polling inférieur à la minute si ce n'est pas nécessaire. Chaque appel à `breakdowns` exécute
  plusieurs agrégations — il compte pour une requête mais reste plus lourd qu'une simple métrique.
</Warning>

## Erreurs

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Both 'start' and 'end' query parameters are required"
  }
  ```

  ```json 429 Too Many Requests theme={null}
  {
    "error": "Rate limit exceeded",
    "scope": "minute",
    "retryAfterSeconds": 42
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": "Internal server error"
  }
  ```
</ResponseExample>