API Documentation

The Global DNS Checker API allows you to programmatically check DNS propagation across our worldwide network of DNS servers. Use it to monitor DNS changes, verify configurations, or integrate DNS checking into your applications.

Base URL

Authentication

All API requests require authentication using an API key. You can create API keys in your account dashboard.

Include your API key in the X-API-Key header with every request:

Keep your API keys secure

Never expose your API keys in client-side code or public repositories. If a key is compromised, delete it immediately and create a new one.

Rate Limits

API requests are rate limited to ensure fair usage and service stability.

Limit Type	Limit
Requests per minute	60
Requests per day	1,000

Rate limit information is included in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Time when the rate limit resets (ISO 8601)

Endpoints

DNS Lookup

Perform a DNS lookup across multiple servers worldwide.

GET /api/v1/lookup

Query Parameters

Parameter	Type	Required	Description
`domain`	string	Yes	The domain name to look up (e.g., example.com)
`type`	string	No	Record type: A, AAAA, CNAME, MX, NS, TXT, SOA, PTR, CAA. Default: A
`servers`	string	No	Comma-separated list of specific server IPs to query

Example Request

curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/lookup?domain=google.com&type=A"

Example Response

{
  "domain": "google.com",
  "recordType": "A",
  "summary": {
    "total": 25,
    "resolved": 24,
    "failed": 1
  },
  "results": [
    {
      "server": {
        "name": "Google Public DNS",
        "ip": "8.8.8.8",
        "country": "US",
        "city": "Mountain View"
      },
      "success": true,
      "records": ["142.250.185.78"],
      "responseTime": 23
    },
    {
      "server": {
        "name": "Cloudflare DNS",
        "ip": "1.1.1.1",
        "country": "US",
        "city": "San Francisco"
      },
      "success": true,
      "records": ["142.250.185.78"],
      "responseTime": 18
    }
  ]
}

List Servers

Get a list of available DNS servers.

GET /api/v1/servers

Query Parameters

Parameter	Type	Required	Description
`country`	string	No	Filter by country code (e.g., US, DE, JP)
`limit`	integer	No	Maximum number of servers to return. Default: 100

Example Request

curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/servers?country=US&limit=10"

Example Response

{
  "total": 10,
  "servers": [
    {
      "name": "Google Public DNS",
      "ip": "8.8.8.8",
      "country": "US",
      "city": "Mountain View",
      "lat": 37.386,
      "lon": -122.0838
    },
    {
      "name": "Cloudflare DNS",
      "ip": "1.1.1.1",
      "country": "US",
      "city": "San Francisco",
      "lat": 37.7749,
      "lon": -122.4194
    }
  ]
}

List Countries

Get a list of countries with available DNS servers.

GET /api/v1/servers/countries

Example Request

curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/servers/countries"

Example Response

{
  "total": 103,
  "countries": [
    { "code": "US", "servers": 45 },
    { "code": "DE", "servers": 23 },
    { "code": "GB", "servers": 18 },
    { "code": "JP", "servers": 15 }
  ]
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Status Code	Description
`200`	Success
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Error Response Format

{
  "error": "Description of what went wrong"
}

Rate Limit Error

{
  "error": "Rate limit exceeded",
  "limit": 60,
  "reset": "2024-01-15T12:00:00.000Z"
}

Code Examples

JavaScript (Node.js)

const response = await fetch(
  '${baseUrl}/lookup?domain=example.com&type=A',
  {
    headers: {
      'X-API-Key': 'dns_your_api_key'
    }
  }
);

const data = await response.json();
console.log(`Resolved: ${data.summary.resolved}/${data.summary.total}`);

Python

import requests

response = requests.get(
    '${baseUrl}/lookup',
    params={'domain': 'example.com', 'type': 'A'},
    headers={'X-API-Key': 'dns_your_api_key'}
)

data = response.json()
print(f"Resolved: {data['summary']['resolved']}/{data['summary']['total']}")

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 
    '${baseUrl}/lookup?domain=example.com&type=A');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: dns_your_api_key'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

echo "Resolved: {$data['summary']['resolved']}/{$data['summary']['total']}";

cURL

# Basic lookup
curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/lookup?domain=example.com"

# Lookup with specific record type
curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/lookup?domain=example.com&type=MX"

# Lookup using specific servers
curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/lookup?domain=example.com&servers=8.8.8.8,1.1.1.1"