NetTrace

API-documentatie

Alles wat je nodig hebt om de NetTrace API in je eigen tools te gebruiken.

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.7

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.

Versies

De huidige versie is v1.7: dns-check geeft het snelste snel-eerst-antwoord tot nu toe (zie hieronder). /v1.6, /v1.5 (wacht op 90% van de resolvers) en /v1.0 (wacht op alle resolvers) blijven werken, zodat bestaande integraties niet breken.

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.7/dns-check -d "domain=nettrace.eu" -d "recordType=A"

curl -X POST https://api.nettrace.eu/v1.7/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 224 resolvers. Elke resolver heeft een eigen timeout van 1,2 seconde; met het snel-eerst-antwoord van v1.7 komt het eerste antwoord meestal binnen 0,07 seconde en is het complete antwoord binnen ~1,2 seconde klaar. Een complete check wordt minimaal 30 seconden gecachet.

Snel-eerst-antwoord (v1.7): het antwoord komt zodra minstens 60% van de resolvers heeft geantwoord (na minimaal 0,03 s), of 45% na 0,1 s, en altijd binnen 0,6 s; staat 85% al klaar, dan meteen. In v1.6 is dat 65% na 0,06 s (max 0,8 s), in v1.5 90% na 0,4 s. Resolvers die nog bezig zijn hebben status: "pending"; NetTrace maakt ze op de achtergrond af, zodat een herhaalde vraag enkele seconden later compleet is. Gebruik wait=all om altijd op alle resolvers te wachten, of ?stream=1 om ze live binnen te krijgen.

ParameterVerplichtBeschrijving
domainjaDomeinnaam (ook IDN). Voor PTR mag ook een IP-adres.
recordTypejaA AAAA MX NS TXT CNAME SOA PTR SRV CAA NAPTR DS DNSKEY
waitneeall = wacht op alle resolvers (standaard in v1.0)
streamnee1 = 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, pending (v1.5/v1.6, nog bezig) 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": 6,
    "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": 11,
    "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.7/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.

ParameterVerplichtBeschrijving
domainjaDomein of e-mailadres.
dkimSelectorneeDKIM-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.

ParameterVerplichtBeschrijving
domainjaDomein; https:// en paden worden genegeerd.
dkim_selectorneeOptionele 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.

ParameterVerplichtBeschrijving
targetjaIP-adres of domein.
modeneeauto (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.

ParameterVerplichtBeschrijving
targetjaIP-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.

POST /site-check

Meet snelheid, SEO en best practices van één pagina en geeft scores van 0–100 (overall, performance, seo, best_practices) plus alle losse checks met status pass, warn, fail of info. Lab-meting zonder browser-rendering. Strengere limiet: gemiddeld 1 check per 20 seconden per IP; resultaten worden 5 minuten gecachet.

ParameterVerplichtBeschrijving
urljaAdres van de pagina; zonder schema wordt https:// gebruikt. Alleen poort 80/443.
{
  "url": "https://example.com/",
  "final_url": "https://example.com/",
  "status": 200,
  "protocol": "HTTP/2.0",
  "timing": {
    "dns_ms": 0,
    "connect_ms": 0,
    "tls_ms": 10,
    "ttfb_ms": 11,
    "download_ms": 0,
    "total_ms": 45
  },
  "page_bytes": 1713,
  "requests": 2,
  "scores": {
    "best_practices": 60,
    "overall": 68,
    "performance": 90,
    "seo": 55
  },
  "checks": [
    {
      "id": "ttfb",
      "category": "performance",
      "status": "pass",
      "value": "11 ms",
      "weight": 20
    },
    {
      "id": "page_weight",
      "category": "performance",
      "status": "pass",
      "value": "2 KB",
      "weight": 15
    },
    {
      "id": "requests",
      "category": "performance",
      "status": "pass",
      "value": "2",
      "weight": 10
    }
  ],
  "note": "Lab measurement from NetTrace's server (Amsterdam) without browser rendering: Core Web Vitals such as LCP and CLS are not measured."
}
  • 400 {"error":"Missing url"}
  • 400 {"error":"Invalid url"}
  • 400 {"error":"Only ports 80 and 443 are allowed"}
  • 429 {"error":"Too many requests, please slow down"}

Overige endpoints

Deze endpoints werken net als de andere (POST, formulier of JSON) en hebben dezelfde strengere limiet als de website-check.

EndpointParameterGeeft terug
POST /whoisdomainregistrar, datums, status, nameservers, DNSSEC (RDAP; voor extensies zonder RDAP: nameservers en DNSSEC uit de DNS plus registry_lookup_url)
POST /subdomain-finderdomainsubdomeinen uit Certificate Transparency (crt.sh, Cert Spotter), NSEC-walking, zoneoverdracht en de eigen DNS-records; elke naam live geverifieerd (actief, wildcard, bestaat niet meer)
POST /mail-server-checkdomainMX-servers: bereikbaarheid poort 25, SMTP-banner, EHLO-extensies, STARTTLS, TLS-versie, certificaat, PTR/FCrDNS, DANE, MTA-STS, TLS-RPT
POST /ssl-checkhostgeldigheid, keten, sleutel, ondersteunde TLS-versies, cipher, OCSP-stapling, HSTS
POST /http-headersurlredirect-keten met headers per stap en een check van de security-headers

GET /resolvers

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

curl https://api.nettrace.eu/v1.7/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.