Ir para o conteúdo

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 exigem uma chave API enviada no cabeçalho Authorization como token Bearer. Chaves na query string são rejeitadas. Gere a sua chave API no painel.

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âmetroTipoObrigatórioDescrição
keystringobrigatórioA sua chave API (começa por tm_)
deststringobrigatórioEndereço IP de destino ou nome de domínio
maxHopsintegeropcionalNúmero máximo de saltos (1-64, predefinido: 30)
protocolstringopcionalProtocolo: 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âmetroTipoDescrição
limitintegerResultados por página (1-100, predefinido: 20)
offsetintegerNúmero de resultados a ignorar (predefinido: 0)
deststringFiltrar 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âmetroTipoObrigatórioDescrição
hoststringobrigatórioEndereço IP ou nome de anfitrião para fazer ping
countintegeropcionalNú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âmetroTipoObrigatórioDescrição
domainstringobrigatórioNome de domínio a resolver
typestringopcionalTipo 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âmetroTipoObrigatórioDescrição
urlstringobrigatórioURL 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âmetroTipoObrigatórioDescrição
hoststringobrigatórioEndereço IP ou nome de anfitrião a verificar
portintegerobrigatórioNúmero da porta a verificar (1-65535)
portsstringopcionalUsar "common" para verificar portas comuns (21, 22, 25, 53, 80, 443, ...)

Exemplo de Resposta

{
  "host": "example.com",
  "resolvedIp": "93.184.216.34",
  "family": 4,
  "port": 443,
  "state": "open",
  "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âmetroTipoObrigatórioDescrição
ipstringobrigatórioEndereço IPv4 ou IPv6 a verificar

Exemplo de Resposta

{
  "ip": "8.8.8.8",
  "reputation": "clean",
  "score": 0,
  "listsAnswered": 5,
  "listsQueried": 5,
  "abuseipdb": {
    "status": "ok",
    "score": 0,
    "totalReports": 12,
    "lastReported": "2026-06-01T10:00:00Z"
  },
  "blacklists": [
    { "name": "Spamhaus ZEN", "status": "clean", "listed": false },
    { "name": "SpamCop", "status": "clean", "listed": false },
    { "name": "Barracuda", "status": "unavailable", "listed": false, "reason": "no_answer" }
  ],
  "geo": {
    "country": "US",
    "isp": "Google LLC",
    "org": "Google LLC",
    "as": "AS15169 Google LLC"
  }
}
GET/api/v1/whois

Dados de registo de um endereço IP público através de RDAP: organização, intervalo de rede, país, contacto de abuso e nome DNS inverso.

Parâmetros

ParâmetroTipoObrigatórioDescrição
ipstringobrigatórioEndereço IPv4 ou IPv6 público a consultar

Exemplo de Resposta

{
  "ip": "8.8.8.8",
  "hostname": "dns.google",
  "org": "Google LLC",
  "netName": "GOGL",
  "netRange": "8.8.8.0/24",
  "country": "US",
  "countrySource": "geoip",
  "abuse": null,
  "registry": "whois.arin.net",
  "asn": "AS15169 Google LLC",
  "reserved": false
}
GET/api/v1/subdomains

Lista os nomes que um domínio certificou, lidos nos registos públicos de transparência de certificados. A resposta indica a fonte que respondeu e se a vista é parcial.

Parâmetros

ParâmetroTipoObrigatórioDescrição
domainstringobrigatórioNome de domínio registável a pesquisar (ex. exemplo.com)

Exemplo de Resposta

{
  "domain": "tracemapper.com",
  "source": "crtsh",
  "sources": [{ "id": "crtsh", "status": "ok" }],
  "partial": false,
  "subdomains": [
    {
      "name": "tracemapper.com",
      "firstSeen": "2026-08-07T00:00:00.000Z",
      "lastSeen": "2026-11-05T01:22:00.000Z",
      "certificates": 1,
      "wildcard": false
    }
  ],
  "certificates": [],
  "totals": { "subdomains": 3, "wildcards": 1, "certificates": 13 },
  "stale": false,
  "fetchedAt": "2026-09-11T07:20:00.000Z"
}
GET/api/v1/email-check

SPF, DKIM, DMARC e MX de um domínio, interpretados. O campo spf.lookups conta os termos que consultam DNS de forma recursiva através de cada include, o limite que os registos ultrapassam em silêncio.

Parâmetros

ParâmetroTipoObrigatórioDescrição
domainstringobrigatórioDomínio de correio a verificar (ex. exemplo.com)
selectorsstringopcionalAté cinco seletores DKIM, separados por vírgulas. Omitido, são experimentados os mais comuns.

Exemplo de Resposta

{
  "domain": "example.com",
  "verdict": "warning",
  "spf": {
    "status": "warning",
    "record": "v=spf1 include:_spf.example.net ~all",
    "lookups": 9,
    "lookupLimit": 10,
    "truncated": false,
    "allQualifier": "~",
    "includes": [{ "domain": "_spf.example.net", "depth": 0, "cost": 9 }],
    "findings": [
      { "code": "spf_lookups_near_limit", "severity": "warning",
        "params": { "count": 9, "limit": 10 } }
    ]
  },
  "dmarc": { "status": "warning", "policy": "none", "rua": ["mailto:d@example.com"], "findings": [] },
  "dkim": { "status": "unknown", "found": [], "selectorsTried": ["default", "google"] },
  "mx": { "status": "ok", "hosts": [{ "host": "mx.example.com", "priority": 10, "resolves": true }] },
  "checkedAt": "2026-09-11T09:30:00.000Z"
}
GET/api/v1/outages

As falhas e perturbações de Internet observadas pela Cloudflare Radar: países e sistemas autónomos afetados, causa declarada, início e fim. Filtre por ASN para saber se uma rede que o seu tráfego atravessa está a reportar um problema. Devolve 503 com um estado unconfigured ou unavailable quando o próprio fluxo não conseguiu responder, o que nunca é o mesmo que uma lista vazia.

Parâmetros

ParâmetroTipoObrigatórioDescrição
rangestringopcionalPeríodo consultado: 1d, 7d (predefinido), 14d ou 28d
asnstringopcionalManter apenas as falhas que afetam este sistema autónomo, por exemplo 3215 ou AS3215

Exemplo de Resposta

{
  "status": "ok",
  "events": [
    {
      "id": "1234",
      "locations": [{ "code": "IQ", "name": "Iraq" }],
      "networks": [{ "asn": 203214, "name": "HulumTele" }],
      "cause": "GOVERNMENT_DIRECTED",
      "outageType": "NATIONWIDE",
      "scope": null,
      "description": "Exam Shutdown",
      "startDate": "2026-09-10T03:30:00.000Z",
      "endDate": "2026-09-10T03:45:00.000Z",
      "ongoing": false,
      "linkedUrl": null
    }
  ],
  "totals": { "ongoing": 0, "ended": 5 },
  "dateRange": "7d",
  "stale": false,
  "fetchedAt": "2026-09-11T07:20:00.000Z"
}
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âmetroTipoObrigatórioDescrição
targetstringobrigatórioEndereç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 60 por minuto por chave API no plano Pro e a 300 por minuto no plano Business. Se exceder este limite, receberá o código 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=_dmarc.example.com&type=TXT&resolver=authoritative"

# 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: an address, a prefix, or an AS number
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/bgp?target=AS15169"

# WHOIS / RDAP
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/whois?ip=8.8.8.8"

# Subdominios dos registos de transparencia de certificados
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/subdomains?domain=example.com"

# Falhas declaradas num sistema autonomo
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/outages?range=7d&asn=AS3215"

# SPF, DKIM, DMARC e MX de um dominio
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/email-check?domain=example.com&selectors=resend"

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"])