---
title: "Documentação da API"
description: "Referência da API webatla: autenticação Bearer, endpoints de dataset e descarregamento, formato de ficheiro JSONL e zstd, limites de taxa e exemplos práticos."
url: https://webatla.com/pt/api-docs
---

# A API da webatla

Traga a base de dados de domínios diretamente para a sua própria stack. Autentique-se com uma chave Bearer, descarregue um dataset inteiro ou uma fatia como JSONL comprimido, e filtre-o localmente. Sem medição por linha.

[Obter uma chave API](https://webatla.com/account/api)
[Especificação OpenAPI](https://webatla.com/api/v1/openapi.json)

REST, sobre HTTPS, respostas JSON

Bearer, autenticação por token, lista branca de IP

JSONL, ficheiros comprimidos com zstd

OpenAPI, especificação 3.1 legível por máquina

## Como funciona a API

A API serve ficheiros inteiros, não um endpoint de consulta em direto. Descarrega um dataset completo ou uma única fatia, e depois divide-o e filtra-o na sua própria máquina. Isso mantém os descarregamentos rápidos e não impõe qualquer limite às suas consultas.

#### 1. Criar uma chave

Gere uma chave de API Bearer na sua conta, opcionalmente limitada a uma lista branca de IP. Envie-a como cabeçalho Authorization.

#### 2. Descarregar ficheiros

Obtenha a exportação completa, ou uma fatia por TLD, sufixo de TLD, país ou tecnologia. Retome descarregamentos interrompidos com um pedido Range.

#### 3. Filtrar localmente

Descomprima com zstd e consulte com jq, um data warehouse ou o seu próprio código. Uma dimensão por fatia, cruze o resto você mesmo.

## Autenticação

A maioria dos endpoints exige uma chave API Bearer. O catálogo de conjuntos de dados está aberto a todos. As descargas de pré-visualização e de amostra exigem uma conta gratuita ou uma chave.

- Crie e faça a gestão das chaves na [sua conta](https://webatla.com/account/api). A chave completa é apresentada uma única vez no momento da criação, por isso guarde-a num local seguro.

- Envie-a como `Authorization: Bearer wbtl_…` em cada pedido autenticado.

- Pode restringir opcionalmente uma chave a uma lista branca de IP. Os pedidos de outros endereços recebem `401`.

- O limite de pedidos aplica-se por chave. Pode rodar ou revogar uma chave a qualquer 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

O contrato completo, legível por máquina, está disponível em [`/api/v1/openapi.json`](https://webatla.com/api/v1/openapi.json) (especificação OpenAPI 3.1).

| Método | Endpoint | Autenticação | Limite de taxa | Propósito |
| --- | --- | --- | --- | --- |
| GET | `/api/v1/datasets` | Público | 60/min | Lista de datasets publicados com preço e número de linhas |
| GET | `/api/v1/preview?dataset={slug}` | Conta ou chave API | 30/min | Amostra gratuita de 10 000 linhas de um dataset completo |
| GET | `/api/v1/sample/{scope}/{key}?dataset={slug}` | Conta ou chave API | 30/min | Amostra gratuita de 20 linhas para uma entidade (TLD, sufixo, país, tecnologia) |
| GET | `/api/v1/me` | Bearer | 200/min | O utilizador e os scopes da chave atual |
| GET | `/api/v1/me/orders` | Bearer | 200/min | As suas encomendas e o respetivo estado |
| GET | `/api/v1/me/downloads` | Bearer | 200/min | O seu histórico de transferências (`?limit=` até 500) |
| GET | `/api/download/{slug}` | Bearer | 240/min | Exportação completa do dataset em formato `.jsonl.zst` |
| GET | `/api/download/{slug}/{scope}/{key}` | Bearer | 240/min | Um segmento de dataset por scope |

`scope` é um de `tld`, `tld_suffix`, `country` ou `technology`. Os endpoints de descarregamento exigem acesso pago e não caducado a esse dataset.

## Início rápido

Cada descarregamento é um único ficheiro. Traga o dataset completo, ou restrinja primeiro a uma única dimensão.

#### Descarregar a exportação completa

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

# Transmite todo o dataset como um único ficheiro .jsonl.zst
```

#### Descarregar uma única fatia

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

# Exatamente uma dimensão por ficheiro. Cruze o resto localmente.
```

#### curl, retoma e filtro local

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

# Retomar uma transferência interrompida com -C -
curl -f -C - -o all-data.jsonl.zst -H "Authorization: Bearer wbtl_•••••••f3a9" \
  https://webatla.com/api/download/all-data

# Ficheiros grandes: o aria2c com 3 ligações paralelas é mais rápido e retoma sozinho
aria2c -x 3 -s 3 -c -o all-data.jsonl.zst \
  --header="Authorization: Bearer wbtl_•••••••f3a9" \
  https://webatla.com/api/download/all-data

# Descomprima e filtre na sua máquina
zstdcat webatla-technologies-WordPress-*.jsonl.zst \
  | jq -c 'select(.["Country by IP"] == "DE")' > wordpress-de.jsonl
```

Liste os descarregamentos anteriores com `GET https://webatla.com/api/v1/me/downloads`. Pré-visualização de qualquer conjunto de dados com a sua chave: `GET https://webatla.com/api/v1/preview?dataset=all-data`.

## Formato dos dados

Os ficheiros são JSON Lines (um objeto JSON por linha), comprimidos com zstd. O esquema é partilhado entre datasets, pelo que os sinais se alinham na mesma chave de domínio.

- Cada linha é um domínio. Descomprima com `zstd -d` ou transmita em fluxo com `zstdcat`.

- Os nomes das colunas podem conter espaços, por isso leia-os com chaves entre colchetes em jq, por exemplo `.["Country by IP"]`.

- Os campos podem estar ausentes ou ser null. Atribua-lhes um valor por omissão, por exemplo `.Registrar // ""`.

- As datas são cadeias ISO 8601, por exemplo `"2026-11-18T04:47:13.573"` ou `"2026-04-22"`.

#### Referência de colunas

| Coluna | Tipo | Exemplo | 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.

* No dataset All data (d6) os campos RDAP/WHOIS estão presentes apenas nos domínios que têm um registo.

#### Formas dos campos aninhados

- `Technologies` é uma lista de nomes ou um objeto que associa cada nome à sua versão.

- `DNS Status` é a cadeia `"TRUE"` ou `"FALSE"`, não um booleano. Para obter os domínios que resolvem, filtre por "TRUE", e não por um objeto DNS records não vazio, porque uma linha FALSE pode conservar os últimos registos conhecidos.

- `DNS records` é um objeto indexado pelo tipo de registo. Cada tipo contém uma lista, exceto SOA, que é um único objeto. As entradas SRV indicam o serviço. À medida que os domínios voltam a ser verificados, as linhas recebem também os campos derivados DKIM, DNSSEC, CDN, ASN, WWW (os registos do host www), MX_TLSA e NULL_MX, que podem ser cadeias de texto, booleanos ou objetos. PARTIAL indica os tipos de registo que não responderam na última verificação. Os seus valores, se existirem, provêm de uma verificação anterior. Os tipos de registo são `A, AAAA, CAA, CNAME, DNSKEY, DS, HTTPS, MX, NS, SOA, SRV, SSHFP, TLSA, TXT`. `MX` é `[{"host", "priority"}]`.

- `Social networks` associa uma plataforma a ligações de perfil: `facebook, instagram, x-twitter, linkedin, youtube, whatsapp, telegram, tiktok, github…`. Estas são as ligações públicas do próprio site, não o contacto de uma pessoa.

- `RDAP/WHOIS Record` contém o registo de inscrição em bruto, expurgado dos campos pessoais segundo as regras da ICANN.

## Receitas

Verificado com ficheiros de exportação reais. Tudo é executado localmente depois de descarregar um ficheiro.

#### Contar, extrair e exportar para CSV

```
# Contar linhas num segmento
zstdcat webatla-all-data-com-*.jsonl.zst | wc -l

# Um domínio por linha
zstdcat webatla-all-data-com-*.jsonl.zst | jq -r '.Domain' > domains.txt

# Colunas selecionadas para CSV
zstdcat webatla-all-data-com-*.jsonl.zst \
  | jq -r '[.Domain, .["Country by IP"] // "", .Registrar // ""] | @csv' > out.csv
```

#### Filtrar por tecnologia

```
# Technologies é um array OU um objeto, trate ambos os casos
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 caducidade

```
# Domínios estacionados ou mortos
zstdcat webatla-dns-com-*.jsonl.zst \
  | jq -r 'select(.["DNS Status"] == "FALSE") | .Domain' > parked.txt

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

# Domínios que expiram em junho de 2026
zstdcat webatla-all-data-com-*.jsonl.zst \
  | jq -r 'select((.["Domain expiration date"] // "") | startswith("2026-06")) | .Domain'
```

#### Python

```
# Descomprimir primeiro
zstd -d webatla-all-data-com-*.jsonl.zst

# Depois transmita linha a linha
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"])
```

## Códigos de resposta e limites

Os erros devolvem um corpo JSON com a forma `{"error": "…"}`. Os cabeçalhos de limite de pedidos são devolvidos em cada pedido.

| Código | Significado |
| --- | --- |
| 200 / 206 | Sucesso. 206 corresponde a uma transferência parcial (retomada). |
| 302 | Falta uma sessão de navegador numa rota de transferência. As chaves API recebem 401 em vez disso. |
| 401 | Chave API em falta, inválida ou bloqueada por IP. |
| 403 | Sem acesso pago ativo a este dataset. |
| 404 | Dataset ou entidade desconhecidos, ou o ficheiro ainda não foi carregado. |
| 416 | Pedido Range mal formado ou multipart. |
| 429 | Limite de pedidos excedido. Aguarde e tente novamente. |

Os endpoints públicos são limitados por IP. Os endpoints autenticados são limitados por chave ou por utilizador, como indicado acima.

## Comece a construir

Crie uma chave na sua conta, ou explore os datasets e obtenha uma amostra com a sua conta gratuita. Perguntas sobre um segmento personalizado? Escreva para support@webatla.com.

[Obter uma chave API](https://webatla.com/account/api)
[Ver datasets](https://webatla.com/pt/pricing)
