---
title: "Documentation API"
description: "Référence API webatla : authentification Bearer, endpoints de dataset et de téléchargement, format de fichier JSONL et zstd, limites de débit et exemples pratiques."
url: https://webatla.com/fr/api-docs
---

# L’API de webatla

Récupérez la base de données de domaines directement dans votre propre stack. Authentifiez-vous avec une clé Bearer, téléchargez un dataset entier ou une tranche au format JSONL compressé, puis filtrez-le en local. Aucune facturation à la ligne.

[Obtenir une clé API](https://webatla.com/account/api)
[Spécification OpenAPI](https://webatla.com/api/v1/openapi.json)

REST, via HTTPS, réponses JSON

Bearer, authentification par token, liste blanche IP

JSONL, fichiers compressés avec zstd

OpenAPI, spécification 3.1 lisible par machine

## Comment fonctionne l’API

L’API fournit des fichiers complets, pas un point d’accès pour des requêtes en direct. Vous téléchargez un dataset complet ou un seul extrait, puis vous le filtrez et le découpez sur votre propre machine. Cela garde les téléchargements rapides et n’impose aucune limite à vos requêtes.

#### 1. Créer une clé

Générez une clé API Bearer dans votre compte, éventuellement restreinte à une liste blanche d’IP. Envoyez-la dans un en-tête Authorization.

#### 2. Télécharger les fichiers

Récupérez l’export complet, ou un segment par TLD, suffixe TLD, pays ou technologie. Reprenez les téléchargements interrompus avec une requête Range.

#### 3. Filtrer localement

Décompressez avec zstd et interrogez avec jq, un data warehouse ou votre propre code. Une dimension par tranche, à vous de croiser le reste.

## Authentification

La plupart des points de terminaison exigent une clé API Bearer. Le catalogue des jeux de données est ouvert à tous. Les téléchargements d'aperçu et d'échantillon demandent un compte gratuit ou une clé.

- Créez et gérez vos clés dans [votre compte](https://webatla.com/account/api). La clé complète s’affiche une seule fois, à la création, conservez-la donc en lieu sûr.

- Envoyez-le comme `Authorization: Bearer wbtl_…` à chaque requête authentifiée.

- Vous pouvez restreindre une clé à une liste blanche d’IP. Les requêtes provenant d’autres adresses reçoivent `401`.

- La limite de débit s’applique par clé. Vous pouvez faire pivoter ou révoquer une clé à tout moment.

```
GET https://webatla.com/api/v1/me
  Authorization: Bearer wbtl_•••••••f3a9

# 200 OK
{
  "user": { "id": "…", "email": "you@example.com", "role": "customer" },
  "apiKeyId": "…",
  "scopes": ["me:read"]
}
```

## Points de terminaison

Le contrat complet, lisible par une machine, se trouve à l’adresse [`/api/v1/openapi.json`](https://webatla.com/api/v1/openapi.json) (OpenAPI 3.1).

| Méthode | Endpoint | Authentification | Limite de débit | Objet |
| --- | --- | --- | --- | --- |
| GET | `/api/v1/datasets` | Public | 60/min | Liste des datasets publiés avec prix et nombre de lignes |
| GET | `/api/v1/preview?dataset={slug}` | Compte ou clé API | 30/min | Échantillon gratuit de 10 000 lignes sur un dataset complet |
| GET | `/api/v1/sample/{scope}/{key}?dataset={slug}` | Compte ou clé API | 30/min | Échantillon gratuit de 20 lignes pour une entité (TLD, suffixe, pays, technologie) |
| GET | `/api/v1/me` | Bearer | 200/min | L’utilisateur et les scopes de la clé actuelle |
| GET | `/api/v1/me/orders` | Bearer | 200/min | Vos commandes et leur statut |
| GET | `/api/v1/me/downloads` | Bearer | 200/min | Votre historique de téléchargements (`?limit=` jusqu’à 500) |
| GET | `/api/download/{slug}` | Bearer | 240/min | Export complet du dataset au format `.jsonl.zst` |
| GET | `/api/download/{slug}/{scope}/{key}` | Bearer | 240/min | Un segment de dataset par scope |

`scope` fait partie de `tld`, `tld_suffix`, `country` ou `technology`. Les points d’accès de téléchargement exigent un accès payant et non expiré à ce dataset.

## Démarrage rapide

Chaque téléchargement correspond à un seul fichier. Récupérez le dataset complet ou limitez-le d’abord à une seule dimension.

#### Télécharger l’export complet

```
GET https://webatla.com/api/download/all-data
  Authorization: Bearer wbtl_•••••••f3a9

# Diffuse tout le dataset en un seul fichier .jsonl.zst
```

#### Télécharger une seule tranche

```
GET https://webatla.com/api/download/all-data/tld/com
https://webatla.com/api/download/all-data/tld_suffix/com.ua
https://webatla.com/api/download/websites-ranking/country/DE
https://webatla.com/api/download/technologies/technology/wordpress
  Authorization: Bearer wbtl_•••••••f3a9

# Une seule dimension par fichier. Croisez le reste en local.
```

#### curl, reprise et filtrage local

```
curl -f -OJ -H "Authorization: Bearer wbtl_•••••••f3a9" \
  https://webatla.com/api/download/technologies/technology/wordpress

# Reprendre un téléchargement interrompu avec -C -
curl -f -C - -o all-data.jsonl.zst -H "Authorization: Bearer wbtl_•••••••f3a9" \
  https://webatla.com/api/download/all-data

# Gros fichiers : aria2c avec 3 connexions parallèles est plus rapide et reprend tout seul
aria2c -x 3 -s 3 -c -o all-data.jsonl.zst \
  --header="Authorization: Bearer wbtl_•••••••f3a9" \
  https://webatla.com/api/download/all-data

# Décompressez et filtrez sur votre machine
zstdcat webatla-technologies-WordPress-*.jsonl.zst \
  | jq -c 'select(.["Country by IP"] == "DE")' > wordpress-de.jsonl
```

Listez vos téléchargements précédents avec `GET https://webatla.com/api/v1/me/downloads`. Aperçu de n'importe quel jeu de données avec votre clé: `GET https://webatla.com/api/v1/preview?dataset=all-data`.

## Format des données

Les fichiers sont au format JSON Lines (un objet JSON par ligne), compressés en zstd. Le schéma est commun à tous les datasets, ce qui permet d’aligner les signaux sur la même clé de domaine.

- Chaque ligne est un domaine. Décompressez-le avec `zstd -d` ou diffusez en flux avec `zstdcat`.

- Les noms de colonnes peuvent contenir des espaces, utilisez donc des clés entre crochets dans jq pour y accéder, par exemple `.["Country by IP"]`.

- Les champs peuvent être manquants ou nuls. Définissez une valeur par défaut, par exemple `.Registrar // ""`.

- Les dates sont des chaînes ISO 8601, par exemple `"2026-11-18T04:47:13.573"` ou `"2026-04-22"`.

#### Référence des colonnes

| Colonne | Type | Exemple | Datasets |
| --- | --- | --- | --- |
| Domain | string | "arriva.com.hr" | d1–d7 |
| TLD suffix | string | "com.hr" | d1–d7 |
| TLD | string | "hr" | d1–d7 |
| Domain type | string: "ICANN" \| "PRIVATE" | "ICANN" | d1–d4, d6, d7 |
| HTTP status | integer \| null | 200 | d3, d6, d7 |
| IP address | string \| null | "31.13.236.27" | d3, d6, d7 |
| Country by IP | string (ISO-2) \| null | "DE" | d2, d3, d6, d7 |
| Social networks | object \| null | {"facebook": ["https://…"]} | d3, d6, d7 |
| Technologies last data checked | string (date) \| null | "2026-04-22" | d3, d6, d7 |
| Technologies | array \| object \| null | ["WordPress"] / {"PHP": "4.4.9"} | d3, d6, d7 |
| DNS last data checked | string (date) | "2026-06-03" | d4, d6, d7 |
| DNS Status | string: "TRUE" \| "FALSE" | "TRUE" | d4, d6, d7 |
| DNS records | object \| null | {"A": ["31.13.236.27"], "MX": [{"host": "…", "priority": 0}]} | d4, d6, d7 |
| PR value | number | 4.808574e-9 / 0 | d2, d3, d6, d7 |
| Harmonic value | number | 10305265 / 0 | d2, d3, d6, d7 |
| RDAP/WHOIS last date checked | string (date) | "2026-01-04" | d5, d7, d6* |
| RDAP/WHOIS method | string: "rdap" \| "whois" | "whois" | d5, d7, d6* |
| Domain creation date | string (ISO 8601) \| null | "2024-12-12T14:04:04" | d2, d3, d5, d6, d7 |
| Domain expiration date | string (ISO 8601) \| null | "2026-12-12T14:04:04" | d2, d3, d5, d6, d7 |
| Domain last changed | string (ISO 8601) \| null | "2026-01-04T04:43:01" | d5, d7, d6* |
| Registrar | string \| null | "REGRU-RU" | d5, d6, d7 |
| RDAP/WHOIS Record | object \| null | {"raw_response": "% TCI Whois…"} | d5, d6* |
| Response Status RDAP/WHOIS | string | "Domain is active" | d5, d6* |

**Datasets:** d1 All active domains · d2 Websites + Ranking · d3 Technologies · d4 DNS · d5 RDAP & WHOIS · d6 All data · d7 Domain Investor.

* Dans All data (d6) les champs RDAP/WHOIS ne sont présents que pour les domaines qui possèdent une fiche d’enregistrement.

#### Structure des champs imbriqués

- `Technologies` est soit un tableau de noms, soit un objet associant chaque nom à sa version.

- `DNS Status` est la chaîne `"TRUE"` ou `"FALSE"`, pas un booléen. Sélectionnez les domaines actifs par « TRUE », et non par un objet DNS records non vide, car une ligne FALSE peut conserver ses derniers enregistrements connus.

- `DNS records` est un objet indexé par type d’enregistrement. Chaque type contient une liste, sauf SOA, qui est un objet unique. Les entrées SRV indiquent le service. À mesure que les domaines sont revérifiés, les lignes reçoivent aussi les champs dérivés DKIM, DNSSEC, CDN, ASN, WWW (les enregistrements de l’hôte www), MX_TLSA et NULL_MX, qui peuvent être des chaînes, des booléens ou des objets. PARTIAL liste les types d’enregistrement qui n’ont pas répondu lors de la dernière vérification. Leurs valeurs éventuelles proviennent d’une vérification antérieure. Les types d’enregistrement sont `A, AAAA, CAA, CNAME, DNSKEY, DS, HTTPS, MX, NS, SOA, SRV, SSHFP, TLSA, TXT`. `MX` est `[{"host", "priority"}]`.

- `Social networks` associe une plateforme à des liens de profil : `facebook, instagram, x-twitter, linkedin, youtube, whatsapp, telegram, tiktok, github…`. Ce sont les liens publics du site lui-même, pas les coordonnées d’une personne.

- `RDAP/WHOIS Record` contient l’enregistrement d’inscription brut, expurgé des champs personnels selon les règles de l’ICANN.

## Recettes

Vérifié sur de vrais fichiers d’export. Tout s’exécute en local une fois le fichier téléchargé.

#### Compter, extraire et exporter en CSV

```
# Compter les lignes d’une tranche
zstdcat webatla-all-data-com-*.jsonl.zst | wc -l

# Un domaine par ligne
zstdcat webatla-all-data-com-*.jsonl.zst | jq -r '.Domain' > domains.txt

# Colonnes sélectionnées vers CSV
zstdcat webatla-all-data-com-*.jsonl.zst \
  | jq -r '[.Domain, .["Country by IP"] // "", .Registrar // ""] | @csv' > out.csv
```

#### Filtrer par technologie

```
# Technologies est un tableau OU un objet, gérez les deux cas
zstdcat webatla-all-data-com-*.jsonl.zst \
  | jq -c 'select(.Technologies
      | if type=="array" then index("WordPress")
        elif type=="object" then has("WordPress")
        else false end)' > wordpress.jsonl
```

#### DNS et expiration

```
# Domaines parqués ou morts
zstdcat webatla-dns-com-*.jsonl.zst \
  | jq -r 'select(.["DNS Status"] == "FALSE") | .Domain' > parked.txt

# A records uniques
zstdcat webatla-dns-com-*.jsonl.zst \
  | jq -r '.["DNS records"].A[]?' | sort -u > ips.txt

# Domaines expirant en juin 2026
zstdcat webatla-all-data-com-*.jsonl.zst \
  | jq -r 'select((.["Domain expiration date"] // "") | startswith("2026-06")) | .Domain'
```

#### Python

```
# Décompresser d’abord
zstd -d webatla-all-data-com-*.jsonl.zst

# Puis lire en flux, ligne par ligne
import json

with open("webatla-all-data-com-2026-06-09.jsonl", encoding="utf-8") as f:
    for line in f:
        row = json.loads(line)
        t = row.get("Technologies")
        names = t if isinstance(t, list) else list(t) if isinstance(t, dict) else []
        if "WordPress" in names and row.get("Country by IP") == "DE":
            print(row["Domain"])
```

## Codes de réponse et limites

Les erreurs renvoient un corps JSON de la forme `{"error": "…"}`. Les en-têtes de limitation de débit sont renvoyés à chaque requête.

| Code | Signification |
| --- | --- |
| 200 / 206 | Succès. 206 correspond à un téléchargement partiel (repris). |
| 302 | Une session de navigateur est absente sur une route de téléchargement. Les clés API reçoivent 401 à la place. |
| 401 | Clé API manquante, invalide ou bloquée par IP. |
| 403 | Aucun accès payant actif à ce dataset. |
| 404 | Dataset ou entité inconnu, ou le fichier n’est pas encore mis en ligne. |
| 416 | Requête Range malformée ou multipart. |
| 429 | Limite de débit dépassée. Patientez puis réessayez. |

Les endpoints publics sont limités par IP. Les endpoints authentifiés sont limités par clé ou par utilisateur, comme indiqué ci-dessus.

## Commencez à construire

Créez une clé dans votre compte, ou parcourez les datasets et récupérez un échantillon avec votre compte gratuit. Des questions sur un extrait personnalisé ? Écrivez à support@webatla.com.

[Obtenir une clé API](https://webatla.com/account/api)
[Voir les datasets](https://webatla.com/fr/pricing)
