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_keyAs 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.
Endpoints
/api/v1/traceExecute 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 |
|---|---|---|---|
| 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) |
| source | string | opcional | Ponto 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
}
]
}/api/v1/tracesListe 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 |
/api/v1/statusObter o estado da API, fontes disponíveis e informações de limites. Sem autenticação necessária.
/api/v1/pingEfetuar 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) |
| family | string | opcional | Versã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
}/api/v1/dnsEfetuar 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, CNAME, MX, NS, TXT, SOA, PTR, CAA ou SRV (predefinido: A). Para PTR, domain pode ser um endereço IP. |
| resolver | string | opcional | Resolvedor 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"]
}/api/v1/http-checkVerificar 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:// é 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
}/api/v1/port-checkVerificar 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 | opcional | Número da porta a verificar (1-65535). Obrigatório exceto se ports=common for indicado. |
| ports | string | opcional | Use "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. |
| timeout | integer | opcional | Tempo 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"
}/api/v1/ip-reputationVerificar 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â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,
"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"
}
}/api/v1/whoisDados 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| ip | string | obrigatório | Endereç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
}/api/v1/subdomainsLista 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| domain | string | obrigatório | Nome 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"
}/api/v1/email-checkSPF, 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| domain | string | obrigatório | Domínio de correio a verificar (ex. exemplo.com) |
| selectors | string | opcional | Até 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"
}/api/v1/outagesAs 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| range | string | opcional | Período consultado: 1d, 7d (predefinido), 14d ou 28d |
| asn | string | opcional | Manter 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"
}/api/v1/bgpConsulte 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| target | string | obrigatório | Endereç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"])