API Documentation

RESTful JSON API for IP intelligence, ASN analysis, BGP routing data, and network infrastructure information.

API Reference
IP Endpoints
ASN Endpoints
Network Tools

Authentication

All API requests require authentication using an API key. You can obtain your API key from the API Keys dashboard.

API Key Authentication

Include your API key in one of these ways:

  • Header (recommended): X-API-Key: YOUR_API_KEY
  • Query parameter: ?api_key=YOUR_API_KEY
https://ip.dnsscience.io/api 
# Example authenticated request
curl "https://ip.dnsscience.io/api/ip/8.8.8.8" \
  -H "X-API-Key: YOUR_API_KEY"

Rate Limits

API rate limits depend on your subscription tier:

Tier Requests/Minute Requests/Month
Free 10 1,000
Professional 60 50,000
Enterprise 300 500,000

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1702656000

Error Handling

The API uses standard HTTP status codes and returns JSON error responses:

{
  "error": "Invalid IP address format",
  "code": "INVALID_IP",
  "status": 400
}
Status Code Description
200Success
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid API key
403Forbidden - Insufficient permissions
404Not Found - Resource not found
429Rate Limited - Too many requests
500Server Error - Internal error

IP Lookup

GET /api/ip/{ip}

Get comprehensive information about an IP address including geolocation, ASN, organization, and reverse DNS.

Parameters
ParameterTypeDescription
ip required string IPv4 or IPv6 address to look up
Example Request
curl "https://ip.dnsscience.io/api/ip/8.8.8.8" \
  -H "X-API-Key: YOUR_API_KEY"
Example Response
{
  "ip": "8.8.8.8",
  "type": "ipv4",
  "asn": "AS15169",
  "org": "Google LLC",
  "isp": "Google LLC",
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "city": "Mountain View",
  "lat": 37.4056,
  "lon": -122.0775,
  "timezone": "America/Los_Angeles",
  "hostname": "dns.google",
  "is_datacenter": true,
  "is_proxy": false,
  "is_vpn": false,
  "is_tor": false
}

My IP

GET /api/geoip/me

Get geolocation and network information for the requesting client's IP address.

Example Request
curl "https://ip.dnsscience.io/api/geoip/me" \
  -H "X-API-Key: YOUR_API_KEY"
Example Response
{
  "ip": "203.0.113.42",
  "country": "Australia",
  "country_code": "AU",
  "region": "New South Wales",
  "city": "Sydney",
  "lat": -33.8688,
  "lon": 151.2093,
  "asn": "AS1221",
  "org": "Telstra Corporation",
  "timezone": "Australia/Sydney"
}

IP Reputation

GET /api/ip/{ip}/reputation

Get threat intelligence and reputation data for an IP address. Checks multiple threat feeds and returns a composite risk score.

Parameters
ParameterTypeDescription
ip required string IP address to check
Example Response
{
  "ip": "1.2.3.4",
  "risk_score": 75,
  "risk_level": "high",
  "threats": [
    {
      "source": "blocklist.de",
      "category": "ssh_bruteforce",
      "last_seen": "2024-01-15T10:30:00Z"
    },
    {
      "source": "cins",
      "category": "scanning",
      "last_seen": "2024-01-14T08:15:00Z"
    }
  ],
  "is_tor_exit": false,
  "is_known_attacker": true,
  "abuse_contacts": ["abuse@example.com"]
}

IP Scan

GET /api/ip/{ip}/scan

Perform a comprehensive scan of an IP address including port detection, service identification, and security analysis.

Query Parameters
ParameterTypeDescription
ports optional string Comma-separated ports to scan (default: common ports)
include_ssl optional boolean Include SSL certificate analysis (default: true)
Example Response
{
  "ip": "93.184.216.34",
  "scan_time": "2024-01-15T12:00:00Z",
  "open_ports": [
    {"port": 80, "service": "http", "product": "nginx"},
    {"port": 443, "service": "https", "product": "nginx"}
  ],
  "ssl_certificate": {
    "issuer": "DigiCert Inc",
    "subject": "*.example.com",
    "valid_from": "2024-01-01T00:00:00Z",
    "valid_until": "2025-01-01T00:00:00Z",
    "fingerprint": "sha256:abc123..."
  },
  "technologies": ["nginx", "Cloudflare"],
  "security_headers": {
    "strict-transport-security": true,
    "content-security-policy": true,
    "x-frame-options": true
  }
}

IP History

GET /api/ip/{ip}/history

Get historical scan data for an IP address.

Query Parameters
ParameterTypeDescription
days optional integer Number of days to look back (default: 30, max: 365)
limit optional integer Maximum records to return (default: 100)

IP BGP Info

GET /api/ip/{ip}/bgp

Get BGP routing information for an IP address including announcing ASN, prefix, and route details.

Example Response
{
  "ip": "8.8.8.8",
  "prefix": "8.8.8.0/24",
  "origin_asn": "AS15169",
  "origin_name": "Google LLC",
  "as_path": ["AS15169"],
  "rpki_status": "valid",
  "rir": "ARIN",
  "announced": true,
  "first_seen": "2009-01-01T00:00:00Z"
}

ASN Lookup

GET /api/asn/{asn}

Get detailed information about an Autonomous System Number including organization, prefixes, and registry data.

Parameters
ParameterTypeDescription
asn required string/integer ASN number (with or without "AS" prefix)
Example Request
curl "https://ip.dnsscience.io/api/asn/15169" \
  -H "X-API-Key: YOUR_API_KEY"
Example Response
{
  "asn": 15169,
  "name": "GOOGLE",
  "org": "Google LLC",
  "country": "US",
  "registry": "arin",
  "allocated": "2000-03-30",
  "type": "Content",
  "prefix_count_v4": 1200,
  "prefix_count_v6": 500,
  "prefixes": [
    "8.8.4.0/24",
    "8.8.8.0/24",
    "8.34.208.0/20"
  ],
  "description": "Google LLC",
  "website": "https://www.google.com"
}

ASN Prefixes

GET /api/asn/{asn}/prefixes

Get all announced IP prefixes for an ASN.

Query Parameters
ParameterTypeDescription
type optional string Filter by IP version: "ipv4" or "ipv6"
limit optional integer Maximum prefixes to return (default: 1000)

ASN Peers

GET /api/asn/{asn}/peers

Get upstream and downstream BGP peers for an ASN.

Example Response
{
  "asn": 15169,
  "upstream": [
    {"asn": 3356, "name": "LUMEN", "relationship": "transit"},
    {"asn": 174, "name": "COGENT", "relationship": "transit"}
  ],
  "downstream": [
    {"asn": 36040, "name": "YOUTUBE", "relationship": "customer"}
  ],
  "peers": [
    {"asn": 13335, "name": "CLOUDFLARE", "relationship": "peer"},
    {"asn": 16509, "name": "AMAZON", "relationship": "peer"}
  ]
}

Visual Traceroute

POST /api/traceroute

Perform a traceroute to a target with geographic visualization data for each hop.

Request Body
ParameterTypeDescription
target required string IP address or domain to trace
max_hops optional integer Maximum number of hops (default: 30)
Example Request
curl -X POST "https://ip.dnsscience.io/api/traceroute" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target": "google.com"}'
Example Response
{
  "target": "google.com",
  "resolved_ip": "142.250.190.78",
  "hops": [
    {
      "hop": 1,
      "ip": "192.168.1.1",
      "hostname": "router.local",
      "rtt_ms": 1.2,
      "lat": null,
      "lon": null
    },
    {
      "hop": 2,
      "ip": "203.0.113.1",
      "hostname": "isp-gateway.example.com",
      "rtt_ms": 12.5,
      "lat": -33.8688,
      "lon": 151.2093,
      "city": "Sydney",
      "country": "AU",
      "asn": "AS1221"
    }
  ],
  "total_hops": 12,
  "total_time_ms": 45.8
}

DNS Lookup

POST /api/dns/lookup

Perform DNS lookups with support for various record types.

Request Body
ParameterTypeDescription
domain required string Domain name to query
type optional string Record type: A, AAAA, MX, TXT, NS, SOA, etc. (default: A)

Data Centers

GET /api/facilities/ip/{ip}

Find data center facilities associated with an IP address or hosting provider.

Example Response
{
  "ip": "8.8.8.8",
  "facilities": [
    {
      "name": "Equinix SV1",
      "city": "San Jose",
      "country": "US",
      "tier": 4,
      "lat": 37.3382,
      "lon": -121.8863,
      "networks_present": ["Google", "Cloudflare", "AWS"]
    }
  ]
}