Documentação da API

Integre o TraceMapper nas suas aplicações com a nossa API REST. Disponível para utilizadores Pro.

Autenticação

Todos os pedidos à API requerem uma chave API passada como parâmetro de consulta "key". Gere a sua chave API a partir do Painel.

Parâmetro de consulta

GET /api/v1/trace?dest=example.com&key=tm_your_api_key

Cabeçalho Authorization (recomendado)

Authorization: Bearer tm_your_api_key

As chaves API expiram após 1 ano. Pode regenerá-las a partir do Painel.

Endpoints

GET/api/v1/trace

Execute um traceroute para um destino e obtenha todos os saltos com dados de geolocalização, ASN, latência, jitter e perda de pacotes.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
key	string	obrigatório	A sua chave API (começa por tm_)
dest	string	obrigatório	Endereço IP de destino ou nome de domínio
maxHops	integer	opcional	Número máximo de saltos (1-64, predefinido: 30)
protocol	string	opcional	Protocolo: icmp, udp ou tcp (predefinido: icmp)

Exemplo de Resposta

{
  "dest": "8.8.8.8",
  "protocol": "icmp",
  "totalHops": 12,
  "hops": [
    {
      "hopNumber": 1,
      "ip": "192.168.1.1",
      "hostname": "router.local",
      "asn": null,
      "asnOrg": null,
      "city": null,
      "country": null,
      "lat": null,
      "lon": null,
      "latencyAvg": 1.2,
      "latencyMin": 0.8,
      "latencyMax": 1.5,
      "jitter": 0.3,
      "packetLoss": 0.0,
      "isTimeout": false
    }
  ]
}

Códigos de Erro

401Chave API em falta ou inválida

403Não é utilizador Pro ou chave inválida

429Limite de pedidos excedido

GET/api/v1/traces

Liste os seus rastreios guardados com paginação. Suporta filtragem por destino.

Parâmetro	Tipo	Descrição
limit	integer	Resultados por página (1-100, predefinido: 20)
offset	integer	Número de resultados a ignorar (predefinido: 0)
dest	string	Filtrar por IP ou nome de domínio de destino

GET/api/v1/status

Obter o estado da API, fontes disponíveis e informações de limites. Sem autenticação necessária.

GET/api/v1/ping

Efetuar um ping a um anfitrião e devolver estatísticas de latência, perda de pacotes e tempos de ida e volta individuais.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
host	string	obrigatório	Endereço IP ou nome de anfitrião para fazer ping
count	integer	opcional	Número de pacotes ping a enviar (1-20, predefinido: 4)

Exemplo de Resposta

{
  "host": "8.8.8.8",
  "resolvedIp": "8.8.8.8",
  "count": 4,
  "sent": 4,
  "received": 4,
  "packetLoss": 0,
  "latency": {
    "min": 1.23,
    "avg": 2.45,
    "max": 3.67,
    "jitter": 0.89
  },
  "rtts": [1.23, 2.45, 3.67, 2.45]
}

GET/api/v1/dns

Efetuar uma consulta DNS para um domínio e devolver os registos resolvidos com o tempo de consulta.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
domain	string	obrigatório	Nome de domínio a resolver
type	string	opcional	Tipo de registo: A, AAAA, MX, NS, CNAME, TXT ou SOA (predefinido: A)

Exemplo de Resposta

{
  "domain": "example.com",
  "type": "A",
  "records": [
    { "address": "93.184.216.34", "ttl": 300 }
  ],
  "queryTime": 12.34,
  "server": "system"
}

GET/api/v1/http-check

Verificar um URL HTTP(S) e devolver o código de estado, tempo de resposta, cadeia de redirecionamentos, cabeçalhos e detalhes do certificado SSL.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
url	string	obrigatório	URL a verificar (https:// adicionado se omitido)

Exemplo de Resposta

{
  "url": "https://example.com",
  "statusCode": 200,
  "statusText": "OK",
  "responseTime": 145,
  "redirects": [],
  "headers": {
    "content-type": "text/html; charset=UTF-8",
    "server": "nginx"
  },
  "ssl": {
    "valid": true,
    "issuer": "DigiCert Inc",
    "validFrom": "2024-01-01",
    "validTo": "2025-01-01",
    "daysRemaining": 180,
    "protocol": "TLSv1.3",
    "sans": ["example.com", "www.example.com"]
  }
}

GET/api/v1/port-check

Verificar se uma porta TCP está aberta num anfitrião e devolver o tempo de resposta e o nome do serviço.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
host	string	obrigatório	Endereço IP ou nome de anfitrião a verificar
port	integer	obrigatório	Número da porta a verificar (1-65535)
ports	string	opcional	Usar "common" para verificar portas comuns (21, 22, 25, 53, 80, 443, ...)

Exemplo de Resposta

{
  "host": "example.com",
  "port": 443,
  "open": true,
  "responseTime": 23,
  "service": "HTTPS"
}

GET/api/v1/ip-reputation

Verificar a reputação de um endereço IP através de listas negras DNS e AbuseIPDB, com dados de geolocalização.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
ip	string	obrigatório	Endereço IPv4 ou IPv6 a verificar

Exemplo de Resposta

{
  "ip": "8.8.8.8",
  "reputation": "clean",
  "score": 0,
  "abuseipdb": {
    "score": 0,
    "totalReports": 12,
    "lastReported": "2025-12-01T10:00:00Z"
  },
  "blacklists": [
    { "name": "Spamhaus ZEN", "listed": false },
    { "name": "SpamCop", "listed": false },
    { "name": "SORBS", "listed": false }
  ],
  "geo": {
    "country": "US",
    "isp": "Google LLC",
    "org": "Google Public DNS",
    "as": "AS15169 Google LLC"
  }
}

GET/api/v1/bgp

Consultar informações de encaminhamento BGP para um endereço IP ou prefixo, incluindo ASN de origem, caminhos AS e fornecedores upstream.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
target	string	obrigatório	Endereço IP ou prefixo (ex.: 8.8.8.0/24)

Exemplo de Resposta

{
  "prefix": "8.8.8.0/24",
  "origin": { "asn": 15169, "holder": "Google LLC" },
  "paths": [
    {
      "collector": "rrc00",
      "asPath": [13335, 15169],
      "communities": ["13335:10000"]
    }
  ],
  "pathCount": 245,
  "collectorCount": 24,
  "upstreamAsns": [
    { "asn": 13335, "holder": "Cloudflare Inc", "count": 45 }
  ]
}

Limites de Pedidos

Os pedidos à API estão limitados a 30 pedidos por minuto por chave API. Se exceder este limite, receberá um código de estado 429 com um cabeçalho Retry-After.

Exemplos de Código

cURL

# Com cabeçalho Authorization
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/trace?dest=8.8.8.8"

# Listar rastreios guardados
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/traces?limit=10"

# Ping
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/ping?host=8.8.8.8&count=4"

# DNS
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/dns?domain=example.com&type=MX"

# HTTP Check
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/http-check?url=https://example.com"

# Port Check
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/port-check?host=example.com&port=443"

# IP Reputation
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/ip-reputation?ip=8.8.8.8"

# BGP
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/bgp?target=8.8.8.0/24"

JavaScript / Node.js

const API_KEY = "tm_your_api_key";
const headers = { Authorization: `Bearer ${API_KEY}` };

// Traceroute
const trace = await fetch(
  "https://tracemapper.com/api/v1/trace?dest=8.8.8.8",
  { headers }
).then(r => r.json());
console.log(trace.hops);

// Ping
const ping = await fetch(
  "https://tracemapper.com/api/v1/ping?host=8.8.8.8",
  { headers }
).then(r => r.json());
console.log(ping.latency);

// DNS
const dns = await fetch(
  "https://tracemapper.com/api/v1/dns?domain=example.com&type=A",
  { headers }
).then(r => r.json());
console.log(dns.records);

Python

import requests

headers = {"Authorization": "Bearer tm_your_api_key"}

# Traceroute
r = requests.get(
    "https://tracemapper.com/api/v1/trace",
    params={"dest": "8.8.8.8"},
    headers=headers,
)
print(r.json()["hops"])

# Ping
r = requests.get(
    "https://tracemapper.com/api/v1/ping",
    params={"host": "8.8.8.8", "count": 4},
    headers=headers,
)
print(r.json()["latency"])

# DNS
r = requests.get(
    "https://tracemapper.com/api/v1/dns",
    params={"domain": "example.com", "type": "MX"},
    headers=headers,
)
print(r.json()["records"])