Documentazione API

Come funziona l’API

L’API fornisce file completi, non un endpoint di query in tempo reale. Scarica un dataset completo o una singola fetta, poi lo suddivide e lo filtra sulla propria macchina. Questo mantiene i download veloci e non impone alcun limite alle query.

1. Creare una chiave

Generi una chiave API Bearer nel proprio account, eventualmente limitata a una lista bianca di IP. La invii come header Authorization.

2. Scaricare i file

Ottenga l’esportazione completa, oppure una fetta per TLD, suffisso TLD, paese o tecnologia. Riprenda i download interrotti con una richiesta Range.

3. Filtrare in locale

Decomprima con zstd e interroghi con jq, un data warehouse o il proprio codice. Una dimensione per fetta, incroci il resto autonomamente.

Autenticazione

La maggior parte degli endpoint richiede una chiave API Bearer. Il catalogo pubblico e gli endpoint preview e sample non richiedono autenticazione.

Crei e gestisca le chiavi nel suo account. La chiave completa viene mostrata una sola volta al momento della creazione, quindi la conservi in un luogo sicuro.
La invii come Authorization: Bearer wbtl_… su ogni richiesta autenticata.
Può restringere facoltativamente una chiave a una lista bianca di IP. Le richieste da altri indirizzi ricevono 401.
Il limite di richieste si applica per chiave. Può ruotare o revocare una chiave in qualsiasi momento.

GEThttps://webatla.com/api/v1/me Authorization: Bearer wbtl_•••••••f3a9 # 200 OK { "user": { "id": "…", "email": "you@example.com", "role": "customer" }, "apiKeyId": "…", "scopes": ["me:read"] }

Endpoints

Il contratto completo, leggibile da una macchina, è disponibile all’indirizzo /api/v1/openapi.json (specifica OpenAPI 3.1).

Metodo	Endpoint	Autenticazione	Limite di frequenza	Scopo
GET	`/api/v1/datasets`	Pubblico	60/min	Elenco dei dataset pubblicati con prezzo e numero di righe
GET	`/api/v1/preview?dataset={slug}`	Pubblico	30/min	Campione gratuito di 10.000 righe di un intero dataset
GET	`/api/v1/sample/{scope}/{key}?dataset={slug}`	Pubblico	30/min	Campione gratuito di 20 righe per un’entità (TLD, suffisso, paese, tecnologia)
GET	`/api/v1/me`	Bearer	200/min	L’utente e gli scope della chiave attuale
GET	`/api/v1/me/orders`	Bearer	200/min	I suoi ordini e il relativo stato
GET	`/api/v1/me/downloads`	Bearer	200/min	La sua cronologia dei download (`?limit=` fino a 500)
GET	`/api/download/{slug}`	Bearer	240/min	Esportazione completa del dataset in formato `.jsonl.zst`
GET	`/api/download/{slug}/{scope}/{key}`	Bearer	240/min	Un segmento di dataset per scope

scope è uno di tld, tld_suffix, country o technology. Gli endpoint di download richiedono un accesso a pagamento e non scaduto a quel dataset.

Avvio rapido

Ogni download è un unico file. Scarichi il dataset completo, oppure lo limiti prima a una sola dimensione.

Scaricare l’esportazione completa

GEThttps://webatla.com/api/download/all-data Authorization: Bearer wbtl_•••••••f3a9 # Trasmette l’intero dataset come un unico file .jsonl.zst

Scaricare una singola fetta

GEThttps://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 # Esattamente una dimensione per file. Incroci il resto localmente.

curl, ripresa e filtro locale

curl -OJ -H "Authorization: Bearer wbtl_•••••••f3a9" \ https://webatla.com/api/download/technologies/technology/wordpress # Riprendere un download interrotto con -C - curl -C - -OJ -H "Authorization: Bearer wbtl_•••••••f3a9" \ https://webatla.com/api/download/all-data # Decomprima e filtri sulla propria macchina zstdcat webatla-technologies-WordPress-*.jsonl.zst \ | jq -c 'select(.["Country by IP"] == "DE")' > wordpress-de.jsonl

Elenchi i download precedenti con GET https://webatla.com/api/v1/me/downloads. Provi un’anteprima gratuita senza chiave: GET https://webatla.com/api/v1/preview?dataset=all-data.

Formato dei dati

I file sono in formato JSON Lines (un oggetto JSON per riga), compressi con zstd. Lo schema è condiviso tra tutti i dataset, quindi i segnali si allineano sulla stessa chiave di dominio.

Ogni riga è un dominio. Decomprima con zstd -d o trasmetta in flusso con zstdcat.
I nomi delle colonne possono contenere spazi, quindi li legga con chiavi tra parentesi quadre in jq, per esempio .["Country by IP"].
I campi possono essere assenti o null. Assegni loro un valore predefinito, per esempio .Registrar // "".
Le date sono stringhe ISO 8601, per esempio "2026-11-18T04:47:13.573" o "2026-04-22".

Riferimento colonne

Colonna	Tipo	Esempio	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.
* Nel dataset All data (d6) i campi RDAP/WHOIS sono presenti solo per i domini che hanno un record di registrazione.

Forme dei campi annidati

Technologies è un elenco di nomi oppure un oggetto che associa ogni nome alla sua versione.
DNS Status è la stringa "TRUE" o "FALSE", non un booleano.
DNS records associa un tipo di record ai suoi valori: A, AAAA, NS, SOA, TXT, MX, CNAME, CAA, HTTPS, DNSKEY, DS, SRV, PTR…. MX è [{"host", "priority"}].
Social networks associa una piattaforma a link di profilo: facebook, instagram, x-twitter, linkedin, youtube, whatsapp, telegram, tiktok, github…. Questi sono i link pubblici del sito stesso, non il contatto di una persona.
RDAP/WHOIS Record contiene il record di registrazione grezzo, con i campi personali oscurati secondo le regole dell’ICANN.

Ricette

Verificato su file di esportazione reali. Tutto viene eseguito in locale dopo aver scaricato un file.

Contare, estrarre ed esportare in CSV

# Contare le righe in un segmento zstdcat webatla-all-data-com-*.jsonl.zst | wc -l # Un dominio per riga zstdcat webatla-all-data-com-*.jsonl.zst | jq -r '.Domain' > domains.txt # Colonne selezionate in CSV zstdcat webatla-all-data-com-*.jsonl.zst \ | jq -r '[.Domain, .["Country by IP"] // "", .Registrar // ""] | @csv' > out.csv

Filtrare per tecnologia

# Technologies è un array O un oggetto, gestisca entrambi i casi 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 e scadenza

# Domini parcheggiati o morti zstdcat webatla-dns-com-*.jsonl.zst \ | jq -r 'select(.["DNS Status"] == "FALSE") | .Domain' > parked.txt # Record A univoci zstdcat webatla-dns-com-*.jsonl.zst \ | jq -r '.["DNS records"].A[]?' | sort -u > ips.txt # Domini in scadenza a giugno 2026 zstdcat webatla-all-data-com-*.jsonl.zst \ | jq -r 'select((.["Domain expiration date"] // "") | startswith("2026-06")) | .Domain'

Python

# Decomprimere prima zstd -d webatla-all-data-com-*.jsonl.zst # Poi lo trasmetta riga per riga 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"])

Codici di risposta e limiti

Gli errori restituiscono un corpo JSON con la forma {"error": "…"}. Le intestazioni di limite di richieste vengono restituite a ogni richiesta.

Codice	Significato
200 / 206	Operazione riuscita. Il 206 corrisponde a un download parziale (ripreso).
302	Manca una sessione del browser su una rotta di download. Le chiavi API ricevono invece 401.
401	Chiave API mancante, non valida o bloccata per IP.
403	Nessun accesso a pagamento attivo a questo dataset.
404	Dataset o entità sconosciuti, o il file non è ancora stato caricato.
416	Richiesta Range malformata o multipart.
429	Limite di richieste superato. Attenda e riprovi.

Gli endpoint pubblici sono limitati per IP. Gli endpoint autenticati sono limitati per chiave o per utente, come indicato sopra.

Inizi a costruire

Crei una chiave nel suo account, oppure esplori i dataset e ottenga prima un campione gratuito. Domande su un segmento personalizzato? Scriva a support@webatla.com.

Ottenere una chiave API Vedere i dataset

L’API di webatla