---
title: "Documentazione API"
description: "Riferimento API webatla: autenticazione Bearer, endpoint di dataset e download, formato file JSONL e zstd, limiti di frequenza ed esempi pratici."
url: https://webatla.com/it/api-docs
---

# L’API di webatla

Porti il database dei domini direttamente nel proprio stack. Si autentichi con una chiave Bearer, scarichi un dataset intero o una fetta come JSONL compresso, e lo filtri in locale. Nessuna misurazione per riga.

[Ottenere una chiave API](https://webatla.com/account/api)
[Specifica OpenAPI](https://webatla.com/api/v1/openapi.json)

REST, su HTTPS, risposte JSON

Bearer, autenticazione tramite token, lista bianca IP

JSONL, file compressi con zstd

OpenAPI, specifica 3.1 leggibile da macchina

## 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 dei dataset è aperto a tutti. I download di anteprima e campione richiedono un account gratuito o una chiave.

- Crei e gestisca le chiavi nel [suo account](https://webatla.com/account/api). 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.

```
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"]
}
```

## Endpoints

Il contratto completo, leggibile da una macchina, è disponibile all’indirizzo [`/api/v1/openapi.json`](https://webatla.com/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}` | Account o chiave API | 30/min | Campione gratuito di 10.000 righe di un intero dataset |
| GET | `/api/v1/sample/{scope}/{key}?dataset={slug}` | Account o chiave API | 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

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

# Trasmette l’intero dataset come un unico file .jsonl.zst
```

#### Scaricare una singola fetta

```
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

# Esattamente una dimensione per file. Incroci il resto localmente.
```

#### curl, ripresa e filtro locale

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

# Riprendere un download interrotto con -C -
curl -f -C - -o all-data.jsonl.zst -H "Authorization: Bearer wbtl_•••••••f3a9" \
  https://webatla.com/api/download/all-data

# File grandi: aria2c con 3 connessioni parallele è più veloce e riprende da solo
aria2c -x 3 -s 3 -c -o all-data.jsonl.zst \
  --header="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`. Anteprima di qualsiasi dataset con la Sua 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. Selezioni i domini attivi in base a "TRUE", non in base a un oggetto DNS records non vuoto, perché una riga FALSE può contenere i suoi ultimi record noti.

- `DNS records` è un oggetto indicizzato per tipo di record. Ogni tipo contiene una lista, tranne SOA, che è un unico oggetto. Le voci SRV indicano il servizio. Man mano che i domini vengono verificati di nuovo, le righe acquisiscono anche i campi derivati DKIM, DNSSEC, CDN, ASN, WWW (i record dell’host www), MX_TLSA e NULL_MX, che possono essere stringhe, booleani o oggetti. PARTIAL elenca i tipi di record che non hanno risposto all’ultima verifica. I loro valori, se presenti, provengono da una verifica precedente. I tipi di record sono `A, AAAA, CAA, CNAME, DNSKEY, DS, HTTPS, MX, NS, SOA, SRV, SSHFP, TLSA, TXT`. `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 un campione con il suo account gratuito. Domande su un segmento personalizzato? Scriva a support@webatla.com.

[Ottenere una chiave API](https://webatla.com/account/api)
[Vedere i dataset](https://webatla.com/it/pricing)
