# JSON API for DNS over HTTPS (DoH)

Previously, web-based applications required browser extensions to use advanced
DNS features such as [DANE](https://en.wikipedia.org/wiki/DANE), [DNS-SD service discovery](http://www.infoq.com/articles/rest-discovery-dns), or even to resolve
anything other than IP addresses -- like MX records.
To use DNSSEC-dependent features like [SSHFP records](https://cloud.google.com/dns/docs/dnssec-advanced#sshfp), any such extensions
would have to validate DNSSEC themselves, as the browser or OS might not do so.

Since 2016, Google Public DNS has offered a web-friendly API for DoH with DNSSEC
validation that does not require browser or OS configuration or extensions.
Simple GET query parameters and JSON responses allow clients to parse the
results using common web APIs and avoid complex DNS message format details like
[pointer compression for domain names](https://www.kb.cert.org/vuls/id/23495/).

See the general [DoH documentation page](https://developers.google.com/speed/public-dns/docs/doh) for information about DoH
generally, such as HTTP headers, redirect handling, privacy best practices, and
HTTP status codes.

The [Secure Transports](https://developers.google.com/speed/public-dns/docs/secure-transports#doh) page has
`curl` command line examples for DoH, and information common to DoH and DNS over
TLS (DoT), such as TLS support and DNS truncation.

## JSON API Specification

All API calls are HTTP GET requests.
In the case of duplicate parameters, only the first value is used.

### Supported parameters

name

:   string, required

    The only required parameter. RFC 4343 backslash escapes are accepted.

    - The length (after replacing backslash escapes) must be between 1 and [253](https://stackoverflow.com/a/28918017/18829) (ignoring an optional trailing dot if present).
    - All labels (parts of the name betweendots) must be 1 to 63 bytes long.
    - Invalid names like `.example.com`, `example..com` or empty string get 400 Bad Request.
    - Non-ASCII characters should be [punycoded](https://en.wikipedia.org/wiki/Punycode) (`xn--qxam`, not `ελ`).

type

:   string, default: `1`

    RR type can be represented as a number in \[1, 65535\] or a canonical string
    (case-insensitive, such as `A` or `aaaa`).
    You can use `255` for 'ANY' queries but be aware that this is *not* a
    replacement for sending queries for both A and AAAA or MX records.
    Authoritative name servers need not return all records for such queries;
    some do not respond, and others (such as cloudflare.com) return only HINFO.

cd

:   boolean, default: `false`

    <br />

    The CD (Checking Disabled) flag.
    Use `cd=1`, or `cd=true` to disable DNSSEC validation;
    use `cd=0`, `cd=false`, or no `cd` parameter to enable DNSSEC validation.

ct

:   string, default: empty

    Desired content type option.

    Use `ct=application/dns-message` to receive a binary DNS message in the
    response HTTP body instead of JSON text.
    Use `ct=application/x-javascript` to explicitly request JSON text.
    Other content type values are ignored and default JSON content is returned.

do

:   boolean, default: `false`

    <br />

    The DO (DNSSEC OK) flag.
    Use `do=1`, or `do=true` to include DNSSEC records (RRSIG, NSEC, NSEC3);
    use `do=0`, `do=false`, or no `do` parameter to omit DNSSEC records.

    Applications should always handle (and ignore, if necessary) any DNSSEC
    records in JSON responses as other implementations may always include them,
    and we may change the default behavior for JSON responses in the future.
    (Binary DNS message responses always respect the value of the DO flag.)

    <br />

edns_client_subnet

:   string, default: empty

    The edns0-client-subnet option. Format is an IP address with a subnet mask.
    Examples: `1.2.3.4/24`, `2001:700:300::/48`.

    If you are using DNS-over-HTTPS because of privacy concerns, and do not want
    *any* part of your IP address to be sent to authoritative name servers
    for geographic location accuracy, use `edns_client_subnet=0.0.0.0/0`.
    Google Public DNS normally sends approximate network information
    (usually zeroing out the last part of your IPv4 address).

random_padding

:   string, ignored

    The value of this parameter is ignored. Example: `XmkMw~o_mgP2pf.gpw-Oi5dK`.

    API clients concerned about possible side-channel privacy attacks using the
    packet sizes of HTTPS GET requests can use this to make all requests exactly
    the same size by padding requests with random data.
    To prevent misinterpretation of the URL, restrict the padding characters
    to the [unreserved URL characters](http://stackoverflow.com/a/695469/18829):
    upper- and lower-case letters, digits, hyphen, period, underscore and tilde.

### DNS response in JSON

A successful response (comments added here are not present in actual responses):

    {
      "Status": 0,  // NOERROR - Standard DNS response code (32 bit integer).
      "TC": false,  // Whether the response is truncated
      "RD": true,   // Always true for Google Public DNS
      "RA": true,   // Always true for Google Public DNS
      "AD": false,  // Whether all response data was validated with DNSSEC
      "CD": false,  // Whether the client asked to disable DNSSEC
      "Question":
      [
        {
          "name": "apple.com.",  // FQDN with trailing dot
          "type": 1              // A - Standard DNS RR type
        }
      ],
      "Answer":
      [
        {
          "name": "apple.com.",   // Always matches name in the Question section
          "type": 1,              // A - Standard DNS RR type
          "TTL": 3599,            // Record's time-to-live in seconds
          "data": "17.178.96.59"  // Data for A - IP address as text
        },
        {
          "name": "apple.com.",
          "type": 1,
          "TTL": 3599,
          "data": "17.172.224.47"
        },
        {
          "name": "apple.com.",
          "type": 1,
          "TTL": 3599,
          "data": "17.142.160.59"
        }
      ],
      "edns_client_subnet": "12.34.56.78/0"  // IP address / scope prefix-length
    }

See [RFC 7871 (EDNS Client Subnet)](https://tools.ietf.org/html/rfc7871) for
details about "scope prefix-length" and how it affects caching.

A failure response with diagnostic information:

    {
      "Status": 2,  // SERVFAIL - Standard DNS response code (32 bit integer).
      "TC": false,  // Whether the response is truncated
      "RD": true,   // Always true for Google Public DNS
      "RA": true,   // Always true for Google Public DNS
      "AD": false,  // Whether all response data was validated with DNSSEC
      "CD": false,  // Whether the client asked to disable DNSSEC
      "Question":
      [
        {
          "name": "dnssec-failed.org.",  // FQDN with trailing dot
          "type": 1                      // A - Standard DNS RR type
        }
      ],
      "Comment": "DNSSEC validation failure. Please check http://dnsviz.net/d/dnssec-failed.org/dnssec/."
    }

SPF and TXT records with embedded quotes and name server attribution:

    {
      "Status": 0,  // NOERROR - Standard DNS response code (32 bit integer).
      "TC": false,  // Whether the response is truncated
      "RD": true,   // Always true for Google Public DNS
      "RA": true,   // Always true for Google Public DNS
      "AD": false,  // Whether all response data was validated with DNSSEC
      "CD": false,  // Whether the client asked to disable DNSSEC
      "Question": [
        {
          "name": "*.dns-example.info.",  // FQDN with trailing dot
          "type": 99                      // SPF - Standard DNS RR type
        }
      ],
      "Answer": [
        {
          "name": "*.dns-example.info.",   // Always matches name in Question
          "type": 99,                      // SPF - Standard DNS RR type
          "TTL": 21599,                    // Record's time-to-live in seconds
          "data": "\"v=spf1 -all\""        // Data for SPF - quoted string
        }
      ],
      "Comment": "Response from 216.239.38.110"
      // Uncached responses are attributed to the authoritative name server
    }

    {
      "Status": 0,  // NOERROR - Standard DNS response code (32 bit integer).
      "TC": false,  // Whether the response is truncated
      "RD": true,   // Always true for Google Public DNS
      "RA": true,   // Always true for Google Public DNS
      "AD": false,  // Whether all response data was validated with DNSSEC
      "CD": false,  // Whether the client asked to disable DNSSEC
      "Question": [
        {
          "name": "s1024._domainkey.yahoo.com.", // FQDN with trailing dot
          "type": 16                             // TXT - Standard DNS RR type
        }
      ],
      "Answer": [
        {
          "name": "s1024._domainkey.yahoo.com.", // Always matches Question name
          "type": 16,                            // TXT - Standard DNS RR type
          "data": "\"k=rsa;  p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDrEee0Ri4Juz+QfiWYui/E9UGSXau/2P8LjnTD8V4Unn+2FAZVGE3kL23bzeoULYv4PeleB3gfm\"\"JiDJOKU3Ns5L4KJAUUHjFwDebt0NP+sBK0VKeTATL2Yr/S3bT/xhy+1xtj4RkdV7fVxTn56Lb4udUnwuxK4V5b5PdOKj/+XcwIDAQAB; n=A 1024 bit key;\""
          // Data for TXT - multiple quoted strings
        }
      ],
    }

### DNS strings

All TXT records are encoded as a single JSON string including uses of longer TXT
record formats such as
[RFC 4408 (SPF)](https://tools.ietf.org/html/rfc4408#section-3.1.3) or
[RFC 4871 (DKIM)](https://tools.ietf.org/html/rfc4871#section-3.6.2.2).

### EDNS

The general [EDNS extension mechanism](https://en.wikipedia.org/wiki/Extension_mechanisms_for_DNS) is not supported.
The EDNS Client Subnet option (edns-client-subnet) is a parameter in the
GET request and a top level field in the JSON response.