Documentation API

Intégrez TraceMapper dans vos applications avec notre API REST.

L'API est incluse dans les offres Pro et Business. Créez votre clé dans le tableau de bord, puis envoyez-la dans l'en-tête Authorization.

Authentification

Toutes les requêtes API exigent une clé API envoyée dans l'en-tête Authorization en tant que jeton Bearer. Une clé passée dans l'URL est refusée. Générez votre clé API depuis le tableau de bord.

En-tête Authorization (recommandé)

Authorization: Bearer tm_your_api_key

Les clés API expirent après 1 an. Vous pouvez les régénérer depuis le Tableau de bord.

Codes d'erreur

Chaque endpoint renvoie ses erreurs en JSON avec un code error stable. Le champ message, quand il existe, est en anglais et destiné à vos journaux : basez votre logique sur le code.

400Paramètre invalide (INVALID_INPUT, INVALID_DESTINATION, INVALID_URL, PORT_NOT_ALLOWED...) ou destination impossible à sonder (UNRESOLVED_HOST, BLOCKED_TARGET pour les adresses privées et réservées).

401Aucune clé d'API : API_KEY_MISSING, ou API_KEY_IN_QUERY quand la clé est passée en ?key= dans l'URL, ce qui est refusé. Envoyez l'en-tête Authorization.

403Clé refusée : API_KEY_INVALID (clé inconnue, ou compte sans offre payante) ou API_KEY_EXPIRED (générez-en une nouvelle depuis le tableau de bord).

429RATE_LIMITED ; TOO_MANY_CONCURRENT sur /trace tant qu'un autre tracé de votre compte est en cours ; GLOBALPING_QUOTA quand le volume horaire de mesures distantes (sources autres que nos serveurs) est épuisé ; PORT_DAILY_LIMIT sur /port-check au-delà de 2 000 ports par jour et par compte ou de 500 par destination (avec scope et limit). Attendez le nombre de secondes indiqué par l'en-tête Retry-After.

502Une source en amont n'a rien répondu d'exploitable (un résolveur DNS, un registre, RIPEstat) : le champ error porte son code (pour le DNS : ESERVFAIL, EREFUSED...). Un échec de notre côté ou en amont n'est pas décompté de votre quota.

503Une limite de notre côté, pas un problème dans votre requête : ce serveur n'a pas de route dans la famille d'adresses demandée (IPV6_UNSUPPORTED, IPV4_UNSUPPORTED), ou une source de données n'a pas répondu (OUTAGES_UNAVAILABLE, OUTAGES_UNCONFIGURED, SOURCES_UNAVAILABLE). Une réponse partielle le dit au lieu d'échouer : dans /bgp, prefixesUnavailable ou neighboursUnavailable à true et prefixCount à null signifient que le nombre n'a pas pu être lu, pas zéro ; dans /whois, registryUnavailable.

Points d'accès

GET/api/v1/trace

Exécute un traceroute vers une destination et retourne tous les sauts avec géolocalisation, ASN, latence, gigue et perte de paquets.

Paramètres

Paramètre	Type	Requis	Description
dest	string	requis	Adresse IP ou nom de domaine de destination
maxHops	integer	optionnel	Nombre maximum de sauts (1-64, par défaut : 30)
protocol	string	optionnel	Protocole : icmp, udp ou tcp (par défaut : icmp)
source	string	optionnel	Point de mesure : local (Falkenstein, par défaut), paris (Gravelines) ou l'identifiant d'un emplacement Globalping, par exemple gp-uk. GET /api/v1/status les liste.

Exemple de réponse

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

Listez vos tracés sauvegardés avec pagination. Filtrage par destination possible.

Paramètre	Type	Description
limit	integer	Résultats par page (1-100, par défaut : 20)
offset	integer	Nombre de résultats à ignorer (par défaut : 0)
dest	string	Filtrer par IP ou nom de domaine de destination

GET/api/v1/status

Obtenir le statut de l'API, les sources disponibles et les limites de requêtes. Aucune authentification requise.

GET/api/v1/ping

Effectuer un ping vers un hôte et retourner les statistiques de latence, la perte de paquets et les temps aller-retour individuels.

Paramètres

Paramètre	Type	Requis	Description
host	string	requis	Adresse IP ou nom d'hôte à pinger
count	integer	optionnel	Nombre de paquets ping à envoyer (1-20, par défaut : 4)
family	string	optionnel	Version IP : auto (par défaut), 4 ou 6. La réponse indique la famille réellement utilisée.

Exemple de réponse

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

Effectuer une résolution DNS pour un domaine et retourner les enregistrements avec le temps de requête.

Paramètres

Paramètre	Type	Requis	Description
domain	string	requis	Nom de domaine à résoudre
type	string	optionnel	Type d'enregistrement : A, AAAA, CNAME, MX, NS, TXT, SOA, PTR, CAA ou SRV (par défaut : A). Pour PTR, domain peut être une adresse IP.
resolver	string	optionnel	Résolveur interrogé : cloudflare (par défaut), google, quad9, opendns ou authoritative (les serveurs de noms de la zone). L'ancienne valeur system est lue comme cloudflare. La réponse nomme les serveurs réellement interrogés.

Exemple de réponse

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

Vérifier une URL HTTP(S) et retourner le code de statut, le temps de réponse, la chaîne de redirections, les en-têtes et les détails du certificat SSL.

Paramètres

Paramètre	Type	Requis	Description
url	string	requis	URL à vérifier (https:// est ajouté s'il manque). Ports 80, 443, 8080 et 8443 uniquement : tout autre port renvoie 400 PORT_NOT_ALLOWED.

Exemple de réponse

{
  "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 vaut false quand aucune réponse HTTP n'a été obtenue, et failure donne alors un code et la raison. Un problème de certificat (expiré, mauvais nom d'hôte, chaîne incomplète) est une réponse, pas une erreur : le statut est 200, avec reachable: false, le code du certificat dans failure et le certificat lui-même dans ssl. security note les en-têtes de sécurité de A à F, un constat par en-tête.

Échec du certificat (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

Vérifier si un port TCP est ouvert sur un hôte et retourner le temps de réponse et le nom du service.

Paramètres

Paramètre	Type	Requis	Description
host	string	requis	Adresse IP ou nom d'hôte à vérifier
port	integer	optionnel	Numéro de port à vérifier (1-65535). Obligatoire sauf si ports=common est fourni.
ports	string	optionnel	Utilisez "common" à la place de port pour balayer les ports courants (21, 22, 25, 53, 80, 443, ...). La réponse porte alors un tableau results, une entrée par port.
timeout	integer	optionnel	Délai de connexion par port, en millisecondes (500-10000, par défaut : 3000).

Exemple de réponse

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

Vérifier la réputation d'une adresse IP via les listes noires DNS et AbuseIPDB, avec données de géolocalisation.

Chaque liste qui inscrit l'adresse précise kind : abuse (spam, machine infectée, réseau détourné) ou policy. Pour Spamhaus ZEN, categories traduit les codes de retour (sbl, css, xbl, drop, pbl). Une inscription PBL (127.0.0.10 ou 127.0.0.11) signale seulement une connexion grand public : elle vaut policy et ne compte pas dans le score.

Paramètres

Paramètre	Type	Requis	Description
ip	string	requis	Adresse IPv4 ou IPv6 à vérifier

Exemple de réponse

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

Données d'enregistrement d'une adresse IP publique via RDAP : organisation, plage réseau, pays, contact abuse et nom DNS inverse.

Paramètres

Paramètre	Type	Requis	Description
ip	string	requis	Adresse IPv4 ou IPv6 publique à consulter

Exemple de réponse

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

Liste les noms qu'un domaine a certifiés, lus dans les journaux publics de transparence des certificats. La réponse indique la source qui a répondu et si la vue est partielle.

Paramètres

Paramètre	Type	Requis	Description
domain	string	requis	Nom de domaine enregistrable à rechercher (ex. exemple.com)

Exemple de réponse

{
  "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 et MX d'un domaine, interprétés. Le champ spf.lookups compte les termes interrogeant le DNS de façon récursive à travers chaque include, la limite que les enregistrements franchissent en silence.

Paramètres

Paramètre	Type	Requis	Description
domain	string	requis	Domaine de messagerie à vérifier (ex. exemple.com)
selectors	string	optionnel	Jusqu'à cinq sélecteurs DKIM, séparés par des virgules. Omis, les plus courants sont essayés.

Exemple de réponse

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

Les pannes et perturbations Internet observées par Cloudflare Radar : pays et systèmes autonomes touchés, cause déclarée, début et fin. Filtrez par ASN pour savoir si un réseau que traverse votre trafic signale un problème. Renvoie 503 avec un statut unconfigured ou unavailable quand le flux lui-même n'a pas pu répondre, ce qui n'est jamais la même chose qu'une liste vide.

Paramètres

Paramètre	Type	Requis	Description
range	string	optionnel	Profondeur d'historique : 1d, 7d (par défaut), 14d ou 28d
asn	string	optionnel	Ne garder que les pannes touchant ce système autonome, par exemple 3215 ou AS3215

Exemple de réponse

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

Consultez les informations de routage BGP d'une adresse IP, d'un préfixe ou d'un système autonome. Pour une adresse ou un préfixe : préfixe annoncé, ASN d'origine, chemins d'AS, fournisseurs amont et statut RPKI. Pour un numéro d'AS : les préfixes qu'il annonce et ses voisins, dans une réponse de forme différente.

Paramètres

Paramètre	Type	Requis	Description
target	string	requis	Adresse IP, préfixe (ex. 8.8.8.0/24) ou numéro d'AS (ex. AS15169)

Réponse pour une adresse ou un préfixe

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

Réponse pour un numéro d'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 requêtes

Tous les endpoints authentifiés, /trace compris, puisent dans un même budget par clé d'API : 60 requêtes par minute avec l'offre Pro et 300 par minute avec l'offre Business. Au-delà, vous recevez un 429 avec un en-tête Retry-After. En plus, un seul tracé par compte s'exécute à la fois, et /port-check ouvre au plus 120 connexions par minute et par compte (ports=common compte chaque port).

Exemples de code

cURL

# Avec en-tête Authorization
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/trace?dest=8.8.8.8"

# Lister les tracés sauvegardés
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"

# Sous-domaines issus des journaux de transparence des certificats
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/subdomains?domain=example.com"

# Pannes déclarées sur un système autonome
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/outages?range=7d&asn=AS3215"

# SPF, DKIM, DMARC et MX d'un domaine
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"])