API Documentation

Integrate TraceMapper into your applications with our REST API. Available for Pro users.

Authentication

All API requests require an API key passed as the "key" query parameter. Generate your API key from the Dashboard.

Query parameter

GET /api/v1/trace?dest=example.com&key=tm_your_api_key

Authorization header (recommended)

Authorization: Bearer tm_your_api_key

API keys expire after 1 year. You can regenerate them from the Dashboard.

Endpoints

GET/api/v1/trace

Run a traceroute to a destination and return all hops with geolocation, ASN, latency, jitter, and packet loss data.

Parameters

Parameter	Type	Required	Description
key	string	required	Your API key (starts with tm_)
dest	string	required	Destination IP address or hostname
maxHops	integer	optional	Maximum number of hops (1-64, default: 30)
protocol	string	optional	Protocol: icmp, udp, or tcp (default: icmp)

Example Response

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

Error Codes

401Missing or invalid API key

403Not a Pro user or invalid key

429Rate limit exceeded

GET/api/v1/traces

List your saved traces with pagination. Supports filtering by destination.

Parameter	Type	Description
limit	integer	Results per page (1-100, default 20)
offset	integer	Number of results to skip (default 0)
dest	string	Filter by destination IP or hostname

GET/api/v1/status

Get API status, available sources, and rate limit info. No authentication required.

GET/api/v1/ping

Ping a host and return latency statistics, packet loss, and individual round-trip times.

Parameters

Parameter	Type	Required	Description
host	string	required	IP address or hostname to ping
count	integer	optional	Number of ping packets to send (1-20, default: 4)

Example Response

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

Perform a DNS lookup for a domain and return the resolved records with query time.

Parameters

Parameter	Type	Required	Description
domain	string	required	Domain name to look up
type	string	optional	Record type: A, AAAA, MX, NS, CNAME, TXT, or SOA (default: A)

Example Response

{
  "domain": "example.com",
  "type": "A",
  "records": [
    { "address": "93.184.216.34", "ttl": 300 }
  ],
  "queryTime": 12.34,
  "server": "system"
}

GET/api/v1/http-check

Check an HTTP(S) URL and return status code, response time, redirect chain, headers, and SSL certificate details.

Parameters

Parameter	Type	Required	Description
url	string	required	URL to check (https:// is added if omitted)

Example Response

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

Check if a TCP port is open on a host and return the response time and service name.

Parameters

Parameter	Type	Required	Description
host	string	required	IP address or hostname to check
port	integer	required	Port number to check (1-65535)
ports	string	optional	Use "common" to scan common ports (21, 22, 25, 53, 80, 443, ...)

Example Response

{
  "host": "example.com",
  "port": 443,
  "open": true,
  "responseTime": 23,
  "service": "HTTPS"
}

GET/api/v1/ip-reputation

Check an IP address reputation against DNS blacklists and AbuseIPDB, with geolocation data.

Parameters

Parameter	Type	Required	Description
ip	string	required	IPv4 or IPv6 address to check

Example Response

{
  "ip": "8.8.8.8",
  "reputation": "clean",
  "score": 0,
  "abuseipdb": {
    "score": 0,
    "totalReports": 12,
    "lastReported": "2025-12-01T10:00:00Z"
  },
  "blacklists": [
    { "name": "Spamhaus ZEN", "listed": false },
    { "name": "SpamCop", "listed": false },
    { "name": "SORBS", "listed": false }
  ],
  "geo": {
    "country": "US",
    "isp": "Google LLC",
    "org": "Google Public DNS",
    "as": "AS15169 Google LLC"
  }
}

GET/api/v1/bgp

Look up BGP routing information for an IP address or prefix, including origin ASN, AS paths, and upstream providers.

Parameters

Parameter	Type	Required	Description
target	string	required	IP address or prefix (e.g. 8.8.8.0/24)

Example Response

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

Rate Limits

API requests are limited to 30 requests per minute per API key. If you exceed this limit, you will receive a 429 status code with a Retry-After header.

Code Examples

cURL

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

# List saved traces
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=example.com&type=MX"

# 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
curl -H "Authorization: Bearer tm_your_api_key" \
  "https://tracemapper.com/api/v1/bgp?target=8.8.8.0/24"

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