DNS Query Tools

What’s this do?

DNS Query Tools is two parts: a DNS query API and a domain parsing API.

DNS Query API

Have you ever setup a domain (often a CNAME or ALIAS) to point to a 3rd-party service provider and then checked their admin portal to see if it’s correct and it tells you, “No, but recent changes may take 48 hours to propagate?” You think you did it right. But maybe not. You can’t tell. And you’ll have to remember to come back 2 days from now to check. (And if it was wrong, try again and wait 2 more days.) Ugh.

Don’t let your app put your users through this misery. The DNS query API always queries the authoritative DNS server, bypassing intermediate caching servers. When your app uses our DNS query API, you’ll always report the actual status of the domain and can tell the user immediately whether they set things up correctly.

Domain Parsing API

Sometimes it’s useful to break apart an domain name into it’s respective components—especially if that domain name is being provided to you by an end user.

The domain parsing API will tell you that www.example.com‘s TLD is com, the domain is example, and the subdomain is www.

It correctly understands 2-part TLDs too, such as www.example.co.uk where the TLD is co.uk.

Further, it translates unicode and emoji domains between their unicode characters and their punycode equivalents (eg: xn--abcd). You may want to render the unicode domain in a UI, but you’ll need to use the punycode equivalent in the backend for subdomain recognition. Or you may even need to be prepared to handle both. The parsing API makes it easy to have this data on hand.

This database is also kept up-to-date, so you don’t have to roll a new software release just to support the latest .toys or .ninja TLD.

How do I use this?

Both APIs are simple REST-style JSON APIs. If you’ve used virtually any modern API, then these will be a cinch to work with.

DNS Queries

By default, queries look for both A and AAAA records. These two requests are equivalent:

GET https://dns.query.tools/v1/dns/query?host=google.com
GET https://dns.query.tools/v1/dns/query?host=google.com&type=A,AAAA

{ "query": {
    "host": "google.com.",
    "type": ["A","AAAA"]
  },
  "results": {
    "A": ["172.217.11.238"],
    "AAAA": ["2607:f8b0:400f:800::200e"]
  }
}

Nearly all other DNS types are supported, including MX, NS, SOA, SRV, and many more.

GET https://dns.query.tools/v1/dns/query?host=example.com&type=MX

When the original DNS record involves a CNAME, both the CNAME and the target record (in this case, an A record) are included in the results. If you ask for an A record, you can safely just use the A response, ignoring the CNAME.

GET https://dns.query.tools/v1/dns/query?host=www.example.com&type=A

{ "query": {
    "host": "www.example.com.",
    "type": ["A"]
  },
  "results": {
    "CNAME": ["example.com."],
    "A": ["173.248.144.226"]
  }
}

Reverse DNS lookups are supported by using the reverse parameter (instead of host). This causes type to default to PTR.

GET https://dns.query.tools/v1/dns/query?reverse=172.217.11.238

Reverse lookups also understand IPv6.

GET https://dns.query.tools/v1/dns/query?reverse=2607:f8b0:400f:800::200e

When there were no records returned, results: {} will be empty.

{ "query": {
    "host": "missing.domain",
    "type": ["A","AAAA"]
  },
  "results": {
  }
}

Domain Parsing

Examples:

GET https://dns.query.tools/v1/domain/parse?host=www.example.com

{ "ascii": {
    "tld": "com",
    "domain": "example",
    "subdomain": "www",
    "fqdn": "www.example.com"
  },
  "unicode": {
    "tld": "com",
    "domain": "example",
    "subdomain": "www",
    "fqdn": "www.example.com"
  }
}

Both unicode (including emoji!) and punycode are accepted. These two return the exact same response.

GET https://dns.query.tools/v1/domain/parse?host=xn--e28h.com
GET https://dns.query.tools/v1/domain/parse?host=😀.com

{ "ascii": {
    "tld": "com",
    "domain": "xn--e28h",
    "subdomain": null,
    "fqdn": "xn--e28h.com"
  },
  "unicode": {
    "tld": "com",
    "domain": "😀",
    "subdomain": null,
    "fqdn": "😀.com"
  }
}

What’s it cost?

It’s free.

We needed this for ourselves. Figuring we couldn’t be the only ones, we thought we’d just share it.

This is the kind of API that’s generally very low use. With that reality in mind, it’s free for up to 10,000 API calls a month. We’ll be surprised if you need more, but if so, let’s have a chat.

The one thing we will do is send you our infrequent newsletter (less than once a month). That’s the place we announce product updates along with other products—including useful APIs like this one.

Even being free, we won’t sell your email or data to anyone. Ever.

Anything else I should know?

That’s everything that’s important.

If you’re ready to start, get your API key now.

And, if you’re interested in more technical background, read on.

The DNS query API always queries the authoritative DNS server instead of the more normal behavior of using intermediate caching servers (these caching servers are why propagation of DNS changes can take so long). Additionally, the API always verifies which server(s) are authoritative for the requested domain.

Querying this way is quite a bit more work than using a typical caching nameserver. Depending on the location of the authoritative nameservers for the domain, it’s not unusual for the API to take a half second or more to respond. This is normal—and explains why everyone uses intermediate caching nameservers!

The API itself will actually keep results in memory for 15 seconds, but that’s it. Identical queries even 16 seconds apart will be freshly retrieved from the authoritative DNS server.

The domain parsing API uses a local database. It is updated regularly to accommodate the rapid expansion of new TLDs these days.

Who made this?

We are Notioneer and we make things. Some larger (AuthRocket) and some smaller (like this).

Login

Signup