Skip to main content

API Reference

ResolverOne uses DNS TXT records to deliver IP Geolocation data. No REST endpoints, no GraphQL, just good old DNS queries.

Base Query Format​

dig TXT [IP_ADDRESS].rslvr.one

Parameters​

  • IP_ADDRESS: Any valid IPv4 address (IPv6 support coming soon)
  • Query Type: Must be TXT
  • Domain: Always .rslvr.one

Response Format​

Pipe-separated string in a DNS TXT record:

"country_code|country|continent|continent_code|asn|as_name|as_domain"

Field Descriptions​

FieldTypeDescriptionExample
country_codeString (2 chars)ISO 3166-1 alpha-2 country codeUS, JP, DE
countryStringFull country nameUnited States, Japan, Germany
continentStringContinent nameNorth America, Asia, Europe
continent_codeString (2 chars)Continent abbreviationNA, AS, EU
asnStringAutonomous System NumberAS15169, AS13335
as_nameStringOrganization nameGoogle LLC, Cloudflare, Inc.
as_domainStringOrganization domaingoogle.com, cloudflare.com

Direct vs Recursive DNS Queries​

ResolverOne supports two query methods: recursive queries (via your ISP/default DNS) and direct queries (straight to our nameservers).

Query our nameservers directly for optimal performance:

# Direct query - fastest and most reliable
dig TXT 8.8.8.8.rslvr.one @rslvr.one

Benefits:

  • Lower latency - Skip the middleman DNS resolution
  • Bypass filtering - ISP DNS filters won't interfere
  • More reliable - Direct connection to our optimized nameservers
  • Consistent performance - No dependency on ISP DNS quality

Recursive Queries​

Standard DNS resolution through your default resolver:

# Recursive query - uses your ISP's DNS
dig TXT 8.8.8.8.rslvr.one

When to use:

  • Testing or debugging DNS propagation
  • When direct queries are blocked by network policies
  • Initial setup validation

Performance Comparison​

# Compare response times
echo "=== Direct Query ==="
time dig TXT 1.1.1.1.rslvr.one @rslvr.one +short

echo "=== Recursive Query ==="
time dig TXT 1.1.1.1.rslvr.one +short

Typical results show 30-70% faster response times with direct queries.

Query Options​

Standard UDP Query​

# Recursive
dig TXT 8.8.8.8.rslvr.one

# Direct
dig TXT 8.8.8.8.rslvr.one @rslvr.one

TCP Query (for unreliable networks)​

# Recursive
dig TXT 8.8.8.8.rslvr.one +tcp

# Direct
dig TXT 8.8.8.8.rslvr.one @rslvr.one +tcp

Short Output (response only)​

# Direct query with clean output
dig TXT 8.8.8.8.rslvr.one @rslvr.one +short

Specify Alternative DNS Server​

# Use Google's DNS for recursive query
dig @8.8.8.8 TXT 1.1.1.1.rslvr.one

Direct Nameserver Queries​

Query our authoritative nameservers directly using @rslvr.one:

dig TXT 8.8.8.8.rslvr.one @rslvr.one

Special Endpoints​

Health Check​

dig TXT health.rslvr.one

Returns: "OK"

Use this to verify our service is running.

Error Handling​

Common DNS Response Codes​

CodeMeaningAction
NOERRORSuccessParse response
NXDOMAINDomain not foundInvalid IP or service issue
SERVFAILServer failureRetry after delay
REFUSEDQuery refusedQuery is not for rslvr.one domain
TIMEOUTQuery timeoutCheck network or retry

REFUSED responses are returned when you query a domain that is not rslvr.one or a subdomain of it. All queries must be for *.rslvr.one domains.

Example Error Handling (Python)​

#!/usr/bin/env python3
# /// script
# dependencies = [
#   "dnspython>=2.0.0",
# ]
# ///

import dns.resolver
import time

def get_location(ip_address, max_retries=3):
    """
    Query ResolverOne for IP geolocation data with retry logic.

    Returns: Pipe-separated location string or None on error
    """
    for attempt in range(max_retries):
        try:
            result = dns.resolver.resolve(f"{ip_address}.rslvr.one", 'TXT')
            return str(result[0]).strip('"')

        except dns.resolver.NXDOMAIN:
            # IP address not found in database (no retry needed)
            print(f"IP not found: {ip_address}")
            return None

        except dns.resolver.NoAnswer:
            # No TXT record exists (no retry needed)
            print(f"No data available for: {ip_address}")
            return None

        except dns.resolver.Timeout:
            # Network timeout (retry with backoff)
            print(f"Timeout on attempt {attempt + 1}/{max_retries}")
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff: 1s, 2s, 4s
                continue

        except Exception as e:
            # Catch-all for other errors (REFUSED, network issues, etc.)
            print(f"Error: {e}")
            if attempt < max_retries - 1:
                time.sleep(1)
                continue
            return None

    print(f"Failed after {max_retries} attempts")
    return None

# Example usage
if __name__ == "__main__":
    # Successful query
    location = get_location("8.8.8.8")
    if location:
        parts = location.split("|")
        print(f"Country: {parts[1]} ({parts[0]})")

    # Handle errors gracefully
    location = get_location("invalid-ip")  # Will return None

Rate Limits & Fair Use​

Currently, no rate limits or usage quotas are enforced during the launch period. We'll provide advance notice of any changes.

Service Level Agreement​

Availability​

  • Launch tier: 99.9% uptime target
  • Enterprise: Custom SLA available

Monitor real-time service status: Service Status Page

Response Times​

  • Target: Sub-second response
  • Typical: 50-200ms
  • Maximum: 5 seconds (before timeout)

Data Freshness​

  • IP Geolocation data updated weekly

Security & Privacy​

Data Collection​

We only log:

  • Query timestamp
  • Queried IP address
  • Requesting IP address (for rate limiting)

We do not log:

  • User agents
  • Detailed request patterns
  • Personal information

Data Retention​

  • Query logs: 30 days
  • Aggregated metrics: 1 year
  • Error logs: 7 days

GDPR Compliance​

  • No personal data collection
  • IP addresses are considered technical data
  • Right to deletion available on request

Need Help?​

When reporting issues, please include example queries and specific error messages. We typically respond within 24 hours.