Documentación API

Integra TraceMapper en tus aplicaciones con nuestra API REST.

La API está incluida en los planes Pro y Business. Crea tu clave en el panel y envíala en la cabecera Authorization.

Autenticación

Todas las solicitudes a la API requieren una clave API enviada en la cabecera Authorization como token Bearer. Las claves en la cadena de consulta se rechazan. Genera tu clave API desde el panel.

Encabezado Authorization (recomendado)

Authorization: Bearer tm_your_api_key

Las claves API expiran después de 1 año. Puedes regenerarlas desde el Panel de control.

Códigos de error

Todos los endpoints devuelven los errores en JSON con un código error estable. El campo message, cuando existe, está en inglés y pensado para sus registros: decida según el código.

400Parámetro no válido (INVALID_INPUT, INVALID_DESTINATION, INVALID_URL, PORT_NOT_ALLOWED...) o destino que no se puede sondear (UNRESOLVED_HOST, BLOCKED_TARGET para direcciones privadas y reservadas).

401Sin clave de API: API_KEY_MISSING, o API_KEY_IN_QUERY cuando la clave se envía como ?key= en la URL, lo cual se rechaza. Envíe la cabecera Authorization.

403Clave rechazada: API_KEY_INVALID (clave desconocida, o la cuenta no tiene un plan de pago) o API_KEY_EXPIRED (genere una nueva desde el panel).

429RATE_LIMITED; TOO_MANY_CONCURRENT en /trace mientras otro trazado de tu cuenta sigue en curso; GLOBALPING_QUOTA cuando se agota el cupo horario de mediciones remotas (fuentes distintas de nuestros servidores); PORT_DAILY_LIMIT en /port-check por encima de 2.000 puertos al día por cuenta o 500 por destino (con scope y limit). Espera los segundos indicados en la cabecera Retry-After.

502Una fuente externa no devolvió nada utilizable (un resolutor DNS, un registro, RIPEstat): el campo error lleva su código (para DNS: ESERVFAIL, EREFUSED...). Un fallo de nuestra parte o de la fuente no se descuenta de tu cuota.

503Una limitación de nuestro lado, no un problema de tu solicitud: este servidor no tiene ruta en la familia de direcciones pedida (IPV6_UNSUPPORTED, IPV4_UNSUPPORTED), o una fuente de datos no respondió (OUTAGES_UNAVAILABLE, OUTAGES_UNCONFIGURED, SOURCES_UNAVAILABLE). Una respuesta parcial lo indica en lugar de fallar: en /bgp, prefixesUnavailable o neighboursUnavailable en true y prefixCount en null significan que no se pudo leer el número, no que sea cero; en /whois, registryUnavailable.

Endpoints

GET/api/v1/trace

Ejecuta un traceroute hacia un destino y devuelve todos los saltos con geolocalización, ASN, latencia, jitter y pérdida de paquetes.

Parámetros

Parámetro	Tipo	Requerido	Descripción
dest	string	requerido	Dirección IP o nombre de dominio de destino
maxHops	integer	opcional	Número máximo de saltos (1-64, por defecto: 30)
protocol	string	opcional	Protocolo: icmp, udp o tcp (por defecto: icmp)
source	string	opcional	Punto de medición: local (Falkenstein, por defecto), paris (Gravelines) o el identificador de una ubicación Globalping, por ejemplo gp-uk. GET /api/v1/status los enumera.

Ejemplo de respuesta

{
  "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

Lista tus traceroutes guardados con paginación. Soporta filtrado por destino.

Parámetro	Tipo	Descripción
limit	integer	Resultados por página (1-100, por defecto: 20)
offset	integer	Número de resultados a omitir (por defecto: 0)
dest	string	Filtrar por IP o nombre de dominio de destino

GET/api/v1/status

Obtener el estado de la API, fuentes disponibles e información de límites. Sin autenticación requerida.

GET/api/v1/ping

Hacer ping a un host y devolver estadísticas de latencia, pérdida de paquetes y tiempos de ida y vuelta individuales.

Parámetros

Parámetro	Tipo	Requerido	Descripción
host	string	requerido	Dirección IP o nombre de host a hacer ping
count	integer	opcional	Número de paquetes ping a enviar (1-20, por defecto: 4)
family	string	opcional	Versión de IP: auto (por defecto), 4 o 6. La respuesta indica la familia realmente usada.

Ejemplo de respuesta

{
  "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

Realizar una consulta DNS para un dominio y devolver los registros resueltos con el tiempo de consulta.

Parámetros

Parámetro	Tipo	Requerido	Descripción
domain	string	requerido	Nombre de dominio a consultar
type	string	opcional	Tipo de registro: A, AAAA, CNAME, MX, NS, TXT, SOA, PTR, CAA o SRV (por defecto: A). Para PTR, domain puede ser una dirección IP.
resolver	string	opcional	Resolutor que responde: cloudflare (por defecto), google, quad9, opendns o authoritative (los servidores de nombres de la zona). El antiguo valor system se interpreta como cloudflare. La respuesta indica los servidores realmente consultados.

Ejemplo de respuesta

{
  "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 una URL HTTP(S) y devolver el código de estado, tiempo de respuesta, cadena de redirecciones, encabezados y detalles del certificado SSL.

Parámetros

Parámetro	Tipo	Requerido	Descripción
url	string	requerido	URL a comprobar (se añade https:// si falta). Solo puertos 80, 443, 8080 y 8443: cualquier otro puerto responde 400 PORT_NOT_ALLOWED.

Ejemplo de respuesta

{
  "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 es false cuando no se obtuvo ninguna respuesta HTTP, y failure da entonces un código y el motivo. Un problema de certificado (caducado, nombre de host incorrecto, cadena incompleta) es una respuesta, no un error: el estado es 200, con reachable: false, el código del certificado en failure y el propio certificado en ssl. security califica las cabeceras de seguridad de A a F, un hallazgo por cabecera.

Fallo del 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 si un puerto TCP está abierto en un host y devolver el tiempo de respuesta y el nombre del servicio.

Parámetros

Parámetro	Tipo	Requerido	Descripción
host	string	requerido	Dirección IP o nombre de host a verificar
port	integer	opcional	Número de puerto a comprobar (1-65535). Obligatorio salvo si se indica ports=common.
ports	string	opcional	Use "common" en lugar de port para escanear los puertos habituales (21, 22, 25, 53, 80, 443, ...). La respuesta incluye entonces un array results, una entrada por puerto.
timeout	integer	opcional	Tiempo de espera de conexión por puerto, en milisegundos (500-10000, por defecto: 3000).

Ejemplo de respuesta

{
  "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 la reputación de una dirección IP contra listas negras DNS y AbuseIPDB, con datos de geolocalización.

Cada lista que incluye la dirección indica un kind: abuse (spam, equipo infectado, red secuestrada) o policy. Para Spamhaus ZEN, categories traduce los códigos de respuesta (sbl, css, xbl, drop, pbl). Una inclusión en la PBL (127.0.0.10 o 127.0.0.11) solo señala una conexión de usuario final: es policy y no cuenta en la puntuación.

Parámetros

Parámetro	Tipo	Requerido	Descripción
ip	string	requerido	Dirección IPv4 o IPv6 a verificar

Ejemplo de respuesta

{
  "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

Datos de registro de una dirección IP pública mediante RDAP: organización, rango de red, país, contacto de abuso y nombre DNS inverso.

Parámetros

Parámetro	Tipo	Requerido	Descripción
ip	string	requerido	Dirección IPv4 o IPv6 pública a consultar

Ejemplo de respuesta

{
  "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 los nombres que un dominio ha certificado, leídos de los registros públicos de transparencia de certificados. La respuesta indica qué fuente respondió y si la vista es parcial.

Parámetros

Parámetro	Tipo	Requerido	Descripción
domain	string	requerido	Nombre de dominio registrable a buscar (p. ej. ejemplo.com)

Ejemplo de respuesta

{
  "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 y MX de un dominio, interpretados. El campo spf.lookups cuenta los términos que consultan DNS de forma recursiva a través de cada include, el límite que los registros cruzan en silencio.

Parámetros

Parámetro	Tipo	Requerido	Descripción
domain	string	requerido	Dominio de correo a comprobar (p. ej. ejemplo.com)
selectors	string	opcional	Hasta cinco selectores DKIM, separados por comas. Si se omite, se prueban los comunes.

Ejemplo de respuesta

{
  "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

Los cortes y perturbaciones de Internet observados por Cloudflare Radar: países y sistemas autónomos afectados, causa declarada, inicio y fin. Filtra por ASN para saber si una red que atraviesa tu tráfico informa de un problema. Devuelve 503 con un estado unconfigured o unavailable cuando el propio flujo no pudo responder, lo que nunca es lo mismo que una lista vacía.

Parámetros

Parámetro	Tipo	Requerido	Descripción
range	string	opcional	Periodo consultado: 1d, 7d (por defecto), 14d o 28d
asn	string	opcional	Conservar solo los cortes que afectan a este sistema autónomo, por ejemplo 3215 o AS3215

Ejemplo de respuesta

{
  "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 la información de enrutamiento BGP de una dirección IP, un prefijo o un sistema autónomo. Para una dirección o un prefijo: prefijo anunciado, ASN de origen, rutas de AS, proveedores ascendentes y estado RPKI. Para un número de AS: los prefijos que anuncia y sus vecinos, con otra forma de respuesta.

Parámetros

Parámetro	Tipo	Requerido	Descripción
target	string	requerido	Dirección IP, prefijo (p. ej. 8.8.8.0/24) o número de AS (p. ej. AS15169)

Respuesta para una dirección o un prefijo

{
  "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 }
  ]
}

Respuesta para un 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" }
  ]
}

Límites de solicitudes

Todos los endpoints autenticados, /trace incluido, comparten un mismo presupuesto por clave de API: 60 solicitudes por minuto en el plan Pro y 300 por minuto en el plan Business. Por encima recibirá un 429 con una cabecera Retry-After. Además, solo se ejecuta un traceroute por cuenta a la vez, y /port-check abre como máximo 120 conexiones por minuto y por cuenta (ports=common cuenta cada puerto).

Ejemplos de código

cURL

# Con encabezado Authorization
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/trace?dest=8.8.8.8"

# Listar trazas guardadas
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 de los registros de transparencia de certificados
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/subdomains?domain=example.com"

# Cortes declarados en un sistema autónomo
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/outages?range=7d&asn=AS3215"

# SPF, DKIM, DMARC y MX de un 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"])