API-documentatie | NetTrace

Introductie

De NetTrace API geeft je dezelfde checks als deze website. Er is geen account of API-sleutel nodig. Basis-URL:

https://api.nettrace.eu/v1.0

De check-endpoints accepteren POST; /resolvers is GET. CORS staat open (Access-Control-Allow-Origin: *), dus je kunt de API ook rechtstreeks vanuit een browser aanroepen.

Requests en antwoorden

Parameters stuur je als formulierdata (application/x-www-form-urlencoded of multipart/form-data) of als JSON. Antwoorden zijn JSON, gecomprimeerd met brotli of gzip als je client dat aangeeft.

curl -X POST https://api.nettrace.eu/v1.0/dns-check -d "domain=nettrace.eu" -d "recordType=A"

curl -X POST https://api.nettrace.eu/v1.0/dns-check \
  -H "Content-Type: application/json" \
  -d '{"domain":"nettrace.eu","recordType":"A"}'

Antwoorden bevatten X-Cache: HIT of MISS en een Cache-Control-header met de resterende cacheduur.

Rate limits en fouten

Per IP-adres geldt gemiddeld 1 request per seconde, met pieken tot 30. Daarboven krijg je 429 met een Retry-After-header. Bij uitzonderlijke drukte kan de API 503 geven, ook met Retry-After. Gecachete antwoorden blijven dan gewoon werken.

400 {"error":"Missing domain"}
405 {"error":"Method not allowed"}
429 {"error":"Too many requests, please slow down"}
503 {"error":"Server busy, please retry"}

`POST /dns-check`

Vraagt een record tegelijk op bij alle 84 resolvers. Elke resolver heeft een eigen timeout van 2 seconden, dus het antwoord komt binnen ongeveer 2 seconden, ook als een resolver niet reageert. Een complete check wordt minimaal 30 seconden gecachet.

Parameter	Verplicht	Beschrijving
`domain`	ja	Domeinnaam (ook IDN). Voor `PTR` mag ook een IP-adres.
`recordType`	ja	`A` `AAAA` `MX` `NS` `TXT` `CNAME` `SOA` `PTR` `SRV` `CAA` `NAPTR` `DS` `DNSKEY`
`stream`	nee	`1` = live resultaten als NDJSON (zie hieronder). Mag ook als querystring.

Antwoord: een array met één object per resolver. status is ok, nodata, nxdomain, timeout, servfail, refused, formerr, notimp, error of down (overgeslagen omdat de resolver bij de healthcheck niet reageerde). formerr en notimp betekenen dat de resolver de vraag niet ondersteunt, bijvoorbeeld een PTR-vraag bij sommige filterresolvers. location_nl bevat de locatie in het Nederlands. rtt_ms is de responstijd van die resolver, of null bij een cache-hit.

[
  {
    "location": "Anycast – nearest PoP (Cisco OpenDNS)",
    "location_nl": "Anycast – dichtstbijzijnde PoP (Cisco OpenDNS)",
    "ip": "208.67.222.220",
    "provider": "OpenDNS",
    "dns_results": [
      {
        "host": "nettrace.eu",
        "priority": 10,
        "target": "mx1.mijn.host",
        "type": "MX"
      },
      {
        "host": "nettrace.eu",
        "priority": 20,
        "target": "mx2.mijn.host",
        "type": "MX"
      }
    ],
    "resolved": true,
    "status": "ok",
    "rtt_ms": 100,
    "cached": false
  },
  {
    "location": "Anycast – nearest PoP (Google Public DNS)",
    "location_nl": "Anycast – dichtstbijzijnde PoP (Google Public DNS)",
    "ip": "8.8.8.8",
    "provider": "Google",
    "dns_results": [
      {
        "host": "nettrace.eu",
        "priority": 20,
        "target": "mx2.mijn.host",
        "type": "MX"
      },
      {
        "host": "nettrace.eu",
        "priority": 10,
        "target": "mx1.mijn.host",
        "type": "MX"
      }
    ],
    "resolved": true,
    "status": "ok",
    "rtt_ms": 10,
    "cached": false
  }
]

400 {"error":"Missing domain"}
400 {"error":"Missing record type"}
400 {"error":"Invalid record type"}
400 {"error":"Invalid domain"}

Live streaming

Met ?stream=1 (of Accept: application/x-ndjson) krijg je elke resolver als losse JSON-regel zodra hij antwoordt, met de extra velden index (vaste volgorde) en total (aantal resolvers).

curl -N -X POST "https://api.nettrace.eu/v1.0/dns-check?stream=1" -d "domain=nettrace.eu" -d "recordType=A"

{"index":37,"total":84,"location":"Anycast – nearest PoP (Cloudflare, secondary)","location_nl":"Anycast – dichtstbijzijnde PoP (Cloudflare, secundair)","ip":"1.0.0.1","provider":"Cloudflare Inc","dns_results":[{"host":"nettrace.eu","ip":"37.1.226.221","type":"A"}],"resolved":true,"status":"ok","rtt_ms":0,"cached":false}
{"index":15,"total":84,"location":"Anycast – nearest PoP (Cloudflare)","location_nl":"Anycast – dichtstbijzijnde PoP (Cloudflare)","ip":"1.1.1.1","provider":"Cloudflare Inc","dns_results":[{"host":"nettrace.eu","ip":"37.1.226.221","type":"A"}],"resolved":true,"status":"ok","rtt_ms":0,"cached":false}

`POST /email-check`

Controleert de e-mailinstellingen van een domein. Als de opgegeven DKIM-selector niets oplevert, worden veelgebruikte selectors automatisch geprobeerd.

Parameter	Verplicht	Beschrijving
`domain`	ja	Domein of e-mailadres.
`dkimSelector`	nee	DKIM-selector, standaard `default`.

{
  "success": true,
  "mxValid": true,
  "disposable": false,
  "deliverable": true,
  "spf": "v=spf1 include:spf.mijn.host ~all",
  "dmarc": "v=DMARC1; p=quarantine; sp=none;",
  "dkim": "Valid DKIM record found for selector x: v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArQIV04gVwTijuLE2uIDyv1z5Jaf5cYyP2zyNXCeqgmQbGSQhaAUHCtFflAgjskALvWF2RpPHaEKs8f9c4sz6IG/cPqIGCzL+19eLLVP0VgBBwtOQwzE7cIFGrIsmucRKfYNtPOnf3sW2HtM4KMZt2hGQ51dxtLva4s8E0cv1nz6nuFZsVTtppr7BTWsTbCSMcGigG4NRKnWvk5pvSGbm+7HulODV6QHMBGG3bNbRFXE/yQxnFDjqTxvwJK7ubK2ouyHERnTy5OaR3hhvqZ2zK8KfQDfjnQ2UToO6zMWnJW7O80chb43JEKjIaUPqua/shhjgEUUuRqERiZ2o7kGVyQIDAQAB",
  "mx": "mx1.mijn.host (priority 10), mx2.mijn.host (priority 20)",
  "ptr": "hosted-by.cablehosting.net",
  "bimi": "BIMI record missing or invalid",
  "google_verification": "Domain is not verified by Google",
  "null_mx": false,
  "dkim_selector": "x"
}

`POST /security-check`

Geeft een score van 0–100 met issues, warnings en improvements, en per onderdeel details: MX, SPF, DMARC, DKIM, BIMI, SSL, HSTS, DNSSEC, CAA, MTA_STS en TLS_RPT. Voor subdomeinen valt de check terug op het hoofddomein.

Parameter	Verplicht	Beschrijving
`domain`	ja	Domein; `https://` en paden worden genegeerd.
`dkim_selector`	nee	Optionele DKIM-selector die als eerste wordt geprobeerd.

{
  "percentage": 75,
  "level": "Medium",
  "issues": [],
  "warnings": [
    "BIMI is not configured.",
    "No CAA records found.",
    "MTA-STS is not configured.",
    "TLS-RPT is not configured."
  ],
  "improvements": [
    "Tighten SPF policy to use \"-all\" after confirming all legitimate senders are included.",
    "Add a \"rua\" tag to DMARC so you receive aggregate reports (e.g. rua=mailto:dmarc@yourdomain.com)."
  ],
  "details": {
    "input_domain": "nettrace.eu",
    "parent_domain": "nettrace.eu",
    "using_parent_fallback": false,
    "SPF": {
      "fallback_used": false,
      "found_on": "nettrace.eu",
      "mode": "softfail (~all)",
      "value": "v=spf1 include:spf.mijn.host ~all"
    },
    "DMARC": {
      "fallback_used": false,
      "found_on": "nettrace.eu",
      "policy": "quarantine",
      "subdomain_policy": "none",
      "value": "v=DMARC1; p=quarantine; sp=none;"
    },
    "HSTS": "Preload-ready"
  }
}

400 {"error":"Missing domain"}
400 {"error":"Invalid domain format"}

`POST /spam-check`

Controleert een IP-adres (IPv4 of IPv6) of domein tegen DNS-blacklists. status per lijst is ok, listed, unavailable (lijst bestaat niet meer publiek) of error.

Parameter	Verplicht	Beschrijving
`target`	ja	IP-adres of domein.
`mode`	nee	`auto` (standaard), `ip`, `domain`

{
  "checked_value": "127.0.0.2",
  "type": "ip",
  "ip": "127.0.0.2",
  "domain": "127.0.0.2",
  "total_lists": 9,
  "listed_count": 9,
  "results": [
    {
      "name": "Spamhaus ZEN",
      "host": "zen.spamhaus.org",
      "listed": true,
      "response": "127.0.0.2",
      "reason": "Listed by XBL, see https://check.spamhaus.org/query/ip/127.0.0.2",
      "list_url": "https://www.spamhaus.org/blocklists/zen-blocklist/",
      "status": "listed"
    },
    {
      "name": "SpamCop",
      "host": "bl.spamcop.net",
      "listed": true,
      "response": "127.0.0.2",
      "reason": "Blocked - see https://www.spamcop.net/bl.shtml?127.0.0.2",
      "list_url": "https://www.spamcop.net/",
      "status": "listed"
    },
    {
      "name": "Barracuda",
      "host": "b.barracudacentral.org",
      "listed": true,
      "response": "127.0.0.2",
      "reason": "http://www.barracudanetworks.com/reputation/?pr=1&ip=127.0.0.2",
      "list_url": "https://www.barracudacentral.org/rbl",
      "status": "listed"
    }
  ]
}

400 {"error":"Missing IP address or domain"}
400 {"error":"Invalid IP address"}
400 {"error":"Invalid domain"}
400 {"error":"Input is neither a valid IP nor a valid domain"}

`POST /ip-info`

Geeft voor een IP-adres, of voor elk IP-adres van een domein (maximaal 8), de hostnaam (reverse DNS), of die hostnaam terugwijst naar het IP (fcrdns), het ASN en de netwerkeigenaar, het IP-blok, het register en de geschatte locatie. Met target=self krijg je je eigen IP-adres. Privé- en gereserveerde adressen krijgen alleen een scope.

Parameter	Verplicht	Beschrijving
`target`	ja	IP-adres (IPv4/IPv6), domein of `self`.

{
  "query": "8.8.8.8",
  "type": "ip",
  "results": [
    {
      "ip": "8.8.8.8",
      "version": 4,
      "scope": "public",
      "hostname": "dns.google",
      "fcrdns": true,
      "network": {
        "asn": 15169,
        "as_name": "Google LLC",
        "prefix": "8.8.8.0/24",
        "registry": "ARIN",
        "allocated": "2023-12-28"
      },
      "location": {
        "country_code": "US",
        "country": "United States",
        "region": "California",
        "city": "Mountain View",
        "continent": "NA",
        "latitude": 37.422,
        "longitude": -122.085,
        "accuracy": "city (approximate)"
      },
      "sources": {
        "geo": [
          {
            "source": "DB-IP Lite",
            "city": "Mountain View",
            "region": "California",
            "country_code": "US",
            "latitude": 37.422,
            "longitude": -122.085
          },
          {
            "source": "MaxMind GeoLite2 (via RIPEstat)",
            "country_code": "US",
            "latitude": 37.751,
            "longitude": -97.822
          }
        ],
        "rir_country": "US",
        "rdap": {
          "name": "GOGL",
          "handle": "NET-8-8-8-0-2",
          "range": "8.8.8.0 – 8.8.8.255",
          "org": "Google LLC",
          "abuse_email": "network-abuse@google.com"
        },
        "bgp": {
          "prefix": "8.8.8.0/24",
          "origin_asns": [
            "15169"
          ]
        }
      }
    }
  ],
  "source": "Location: DB-IP (db-ip.com, CC BY 4.0) and MaxMind GeoLite2 via RIPEstat. ASN: DB-IP. Prefix/registry: Team Cymru. Registration: RDAP. Routing and RIR country: RIPEstat."
}

Bronnen: DB-IP (CC BY 4.0), MaxMind GeoLite2 via RIPEstat, RDAP, RIPE NCC (BGP/RIR) en Team Cymru. Het veld sources bevat per bron de ruwe uitkomst.

`GET /resolvers`

Lijst van alle actieve resolvers met hun actuele status, zoals op de statuspagina.

curl https://api.nettrace.eu/v1.0/resolvers

{
  "count": 84,
  "standby": 17,
  "recent_replacements": [],
  "resolvers": [
    {
      "ip": "208.67.222.220",
      "provider": "OpenDNS",
      "location": "Anycast – nearest PoP (Cisco OpenDNS)",
      "location_nl": "Anycast – dichtstbijzijnde PoP (Cisco OpenDNS)",
      "legacy_location": "San Francisco CA, United States",
      "enabled": true,
      "up": true
    },
    {
      "ip": "8.8.8.8",
      "provider": "Google",
      "location": "Anycast – nearest PoP (Google Public DNS)",
      "location_nl": "Anycast – dichtstbijzijnde PoP (Google Public DNS)",
      "legacy_location": "Mountain View CA, United States",
      "enabled": true,
      "up": true
    }
  ]
}

OpenAPI

De volledige specificatie staat in /openapi.json (OpenAPI 3.0). Daarmee kun je in de meeste talen automatisch een client genereren.