DNS Records Database Format Documentation

Overview

Merklemap's dns records database is a comprehensive DNS records dataset containing query results for over 700 million unique hostnames worldwide. The database stores detailed DNS record information including A, AAAA, MX, NS, SOA, TXT, and other record types, along with their query timestamps and response status. Each record is stored in a structured format that allows for efficient querying and analysis of global DNS infrastructure.

File Structure

Each entry in the database follows this general structure:

{
  "hostname": "example.com",
  "results": [
    {
      "success": {
        "query": "example.com IN A",
        "query_timestamp": "2024-10-22T21:48:45.415226364Z",
        "records": {
          "A": ["192.0.2.1", "192.0.2.2"]
        }
      }
    }
  ]
}

Record Types

The database supports multiple DNS record types including:

• A Records: IPv4 addresses
• AAAA Records: IPv6 addresses
• MX Records: Mail exchange servers
• NS Records: Name servers
• SOA Records: Start of authority
• TXT Records: Text records
• CNAME Records: Canonical names
• CAA Records: Certificate authority authorization
• HTTPS Records: HTTPS service bindings
• SRV Records: Service records
• PTR Records: Pointer records
• NAPTR Records: Name authority pointer records
• SVCB Records: Service binding records
• TLSA Records: TLS authentication records

Query Format

Queries are formatted as: [hostname] IN [record_type]

Example: example.com IN A

Timestamps

• All timestamps are in ISO 8601 format
• Includes microsecond precision
• Uses UTC timezone (Z suffix)
• Format: YYYY-MM-DDThh:mm:ss.SSSSSSZ

Response Types

Success Response

{
  "success": {
    "query": "example.com IN A",
    "query_timestamp": "2024-10-22T21:48:45.415226364Z",
    "records": {
      "A": ["192.0.2.1"]
    }
  }
}

Error Response

{
  "error": {
    "query": "example.com IN TXT",
    "query_timestamp": "2024-10-22T21:48:45.415226364Z",
    "error": "Server Failure"
  }
}

Common Error Types

• Server Failure
• Non-Existent Domain

CNAME Resolution

• CNAME records may be followed by the resolved records
• Multiple CNAME chains are supported
• Final resolution is included in the records

Example:

{
  "CNAME": ["www.example.com."],
  "A": ["192.0.2.1"]
}

Special Cases

Multiple Values

Records that can have multiple values (like MX or NS) are represented as arrays:

{
  "MX": [
    "10 mail1.example.com.",
    "20 mail2.example.com."
  ]
}

Priority Values

Some record types include priority values:

• MX records: Priority number preceding the mail server
• SRV records: Priority, weight, and port numbers

Example Usage

Complete entry example:

{
  "hostname": "example.com",
  "results": [
    {
      "success": {
        "query": "example.com IN A",
        "query_timestamp": "2024-10-22T21:48:45.415226364Z",
        "records": {
          "A": ["192.0.2.1"]
        }
      }
    },
    {
      "success": {
        "query": "example.com IN AAAA",
        "query_timestamp": "2024-10-22T21:48:45.415230295Z",
        "records": {
          "AAAA": ["2001:db8::1"]
        }
      }
    },
    {
      "success": {
        "query": "example.com IN MX",
        "query_timestamp": "2024-10-22T21:48:45.415235295Z",
        "records": {
          "MX": [
            "10 mail1.example.com.",
            "20 mail2.example.com."
          ]
        }
      }
    },
    {
      "success": {
        "query": "example.com IN NS",
        "query_timestamp": "2024-10-22T21:48:45.415240295Z",
        "records": {
          "NS": [
            "ns1.example.com.",
            "ns2.example.com."
          ]
        }
      }
    }
  ]
}

IP Address Ranges Used in Examples

• IPv4: 192.0.2.0/24 (TEST-NET-1, reserved for documentation)
• IPv6: 2001:db8::/32 (Reserved for documentation and examples)