Ir para o conteúdo

Documentação da API

Integre o TraceMapper nas suas aplicações com a nossa API REST.

A API está incluída nos planos Pro e Business. Crie a sua chave no painel e envie-a no cabeçalho Authorization.

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.

Códigos de Erro

Todos os endpoints devolvem os erros em JSON com um código error estável. O campo message, quando existe, está em inglês e destina-se aos seus registos: baseie a lógica no código.

400Parâmetro inválido (INVALID_INPUT, INVALID_DESTINATION, INVALID_URL, PORT_NOT_ALLOWED...) ou destino que não pode ser sondado (UNRESOLVED_HOST, BLOCKED_TARGET para endereços privados e reservados).
401Sem chave de API: API_KEY_MISSING, ou API_KEY_IN_QUERY quando a chave é enviada como ?key= no URL, o que é recusado. Envie o cabeçalho Authorization.
403Chave recusada: API_KEY_INVALID (chave desconhecida, ou conta sem plano pago) ou API_KEY_EXPIRED (gere uma nova no painel).
429RATE_LIMITED; TOO_MANY_CONCURRENT em /trace enquanto outro traçado da sua conta ainda decorre; GLOBALPING_QUOTA quando a quota horária de medições remotas (fontes que não os nossos servidores) se esgota; PORT_DAILY_LIMIT em /port-check acima de 2000 portas por dia por conta ou 500 por destino (com scope e limit). Aguarde os segundos indicados no cabeçalho Retry-After.
502Uma fonte externa não devolveu nada utilizável (um resolvedor DNS, um registo, RIPEstat): o campo error traz o seu código (para DNS: ESERVFAIL, EREFUSED...). Uma falha do nosso lado ou da fonte não é descontada da sua quota.
503Uma limitação do nosso lado, não um problema no seu pedido: este servidor não tem rota na família de endereços pedida (IPV6_UNSUPPORTED, IPV4_UNSUPPORTED), ou uma fonte de dados não respondeu (OUTAGES_UNAVAILABLE, OUTAGES_UNCONFIGURED, SOURCES_UNAVAILABLE). Uma resposta parcial indica-o em vez de falhar: em /bgp, prefixesUnavailable ou neighboursUnavailable a true e prefixCount a null significam que o número não pôde ser lido, não zero; em /whois, registryUnavailable.

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
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)
sourcestringopcionalPonto de medição: local (Falkenstein, predefinido), paris (Gravelines) ou o identificador de uma localização Globalping, por exemplo gp-uk. GET /api/v1/status lista-os.

Exemplo de Resposta

{
  "dest": "8.8.8.8",
  "source": "local",
  "protocol": "icmp",
  "status": "completed",
  "address": "8.8.8.8",
  "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
    }
  ]
}
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)
familystringopcionalVersão IP: auto (predefinido), 4 ou 6. A resposta indica a família realmente usada.

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],
  "family": 4
}
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, CNAME, MX, NS, TXT, SOA, PTR, CAA ou SRV (predefinido: A). Para PTR, domain pode ser um endereço IP.
resolverstringopcionalResolvedor que responde: cloudflare (predefinido), google, quad9, opendns ou authoritative (os servidores de nomes da zona). O antigo valor system é lido como cloudflare. A resposta indica os servidores realmente consultados.

Exemplo de Resposta

{
  "domain": "example.com",
  "type": "A",
  "records": [
    { "address": "93.184.216.34", "ttl": 300 }
  ],
  "queryTime": 12.34,
  "server": "cloudflare",
  "servers": ["1.1.1.1", "1.0.0.1"]
}
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:// é acrescentado se faltar). Apenas as portas 80, 443, 8080 e 8443: qualquer outra porta devolve 400 PORT_NOT_ALLOWED.

Exemplo de Resposta

{
  "url": "https://example.com",
  "reachable": true,
  "failure": null,
  "statusCode": 200,
  "statusText": "OK",
  "responseTime": 145,
  "redirects": [],
  "headers": {
    "content-type": "text/html; charset=UTF-8",
    "server": "nginx"
  },
  "ssl": {
    "valid": true,
    "problem": null,
    "problemCode": null,
    "issuer": "DigiCert Inc",
    "validFrom": "2026-01-01",
    "validTo": "2027-01-01",
    "daysRemaining": 180,
    "protocol": "TLSv1.3",
    "sans": ["example.com", "www.example.com"]
  },
  "security": {
    "grade": "B",
    "score": 75,
    "findings": [
      { "key": "strict-transport-security", "present": true,
        "value": "max-age=31536000", "status": "ok" },
      { "key": "content-security-policy", "present": false,
        "value": null, "status": "missing" }
    ]
  },
  "resolvedIp": "93.184.216.34",
  "family": 4
}

reachable é false quando não foi obtida nenhuma resposta HTTP, e failure indica então um código e o motivo. Um problema de certificado (expirado, nome de anfitrião errado, cadeia incompleta) é uma resposta, não um erro: o estado é 200, com reachable: false, o código do certificado em failure e o próprio certificado em ssl. security classifica os cabeçalhos de segurança de A a F, uma constatação por cabeçalho.

Falha do certificado (HTTP 200)

{
  "url": "https://expired.example.com",
  "reachable": false,
  "failure": {
    "code": "CERT_HAS_EXPIRED",
    "message": "The certificate has expired."
  },
  "statusCode": null,
  "ssl": {
    "valid": false,
    "problemCode": "CERT_HAS_EXPIRED",
    "validTo": "2026-01-01",
    "daysRemaining": -267
  },
  "security": null
}
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
portintegeropcionalNúmero da porta a verificar (1-65535). Obrigatório exceto se ports=common for indicado.
portsstringopcionalUse "common" em vez de port para analisar as portas comuns (21, 22, 25, 53, 80, 443, ...). A resposta inclui então um array results, uma entrada por porta.
timeoutintegeropcionalTempo limite de ligação por porta, em milissegundos (500-10000, predefinido: 3000).

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.

Cada lista que inclui o endereço indica um kind: abuse (spam, máquina infetada, rede sequestrada) ou policy. Para a Spamhaus ZEN, categories traduz os códigos de resposta (sbl, css, xbl, drop, pbl). Uma inclusão na PBL (127.0.0.10 ou 127.0.0.11) só assinala uma ligação de utilizador final: é policy e não conta para a pontuaçã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": "network-abuse@google.com",
  "registry": "whois.arin.net",
  "registryUnavailable": false,
  "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

Consulte as informações de encaminhamento BGP de um endereço IP, de um prefixo ou de um sistema autónomo. Para um endereço ou prefixo: prefixo anunciado, ASN de origem, caminhos de AS, fornecedores a montante e estado RPKI. Para um número de AS: os prefixos que anuncia e os seus vizinhos, numa resposta com outra forma.

Parâmetros

ParâmetroTipoObrigatórioDescrição
targetstringobrigatórioEndereço IP, prefixo (ex. 8.8.8.0/24) ou número de AS (ex. AS15169)

Resposta para um endereço ou um prefixo

{
  "kind": "prefix",
  "target": "8.8.8.8",
  "prefix": "8.8.8.0/24",
  "allocationBlock": "8.0.0.0/8",
  "announced": true,
  "origin": { "asn": 15169, "holder": "Google LLC" },
  "rpki": "valid",
  "paths": [
    {
      "collector": "rrc00",
      "peer": "80.249.208.1",
      "asPath": [13335, 15169],
      "asPathCollapsed": [13335, 15169],
      "communities": ["13335:10000"]
    }
  ],
  "pathCount": 245,
  "collectorCount": 24,
  "upstreamAsns": [
    { "asn": 13335, "holder": "Cloudflare Inc", "count": 45 }
  ]
}

Resposta para um número de AS (target=AS15169)

{
  "kind": "asn",
  "target": "AS15169",
  "asn": 15169,
  "holder": "GOOGLE - Google LLC",
  "announced": true,
  "prefixCount": 1024,
  "prefixes": ["8.8.8.0/24", "8.8.4.0/24"],
  "prefixesTruncated": true,
  "prefixesUnavailable": false,
  "neighboursUnavailable": false,
  "neighbours": [
    { "asn": 3356, "holder": "LEVEL3", "relation": "upstream" },
    { "asn": 36040, "holder": "YOUTUBE", "relation": "downstream" }
  ]
}

Limites de Pedidos

Todos os endpoints autenticados, incluindo /trace, partilham um mesmo orçamento por chave de API: 60 pedidos por minuto no plano Pro e 300 por minuto no plano Business. Acima disso recebe um 429 com um cabeçalho Retry-After. Além disso, só corre um traceroute por conta de cada vez, e /port-check abre no máximo 120 ligações por minuto e por conta (ports=common conta cada porta).

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 autónomo
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 domínio
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"])