How to use host.io
Documentation

Authentication

Your API token is used to authenticate you with our API, and can be provided either as an HTTP Basic Auth username, a bearer token, or alternatively as a token URL parameter.

If no token is provided, you will receive an error message response with an HTTP 400 status code.

Basic Auth
curl -u $TOKEN: https://host.io
Bearer Token
curl -H "Authorization: Bearer $TOKEN" https://host.io
Query Parameter
curl "https://host.io?token=$TOKEN"

Pagination and Limits

API endpoints that return a list of domains (for eg, /api/domains/ip/:domain which returns a list of domains on a particular IP) can be paginated by using query parameters 'page' and 'limit'.

The following code will return 50 domains for the IP 8.8.8.8 starting from 250th.

curl "https://host.io/api/domains/ip/8.8.8.8?limit=50&page=5&token=$TOKEN"

The max limit is 1000.

It's important to note that the maximum number of domains you can request is subject to your plan. For example, with free plan you can request maximum of 5 domains per page. Please check pricing page to see how many domains you can request per API call.

/api/web/:domain

Description

Metadata scraped from a domain homepage.

Errors

Returns the HTTP 404 status code as well as an error message in JSON format if the domain is invalid and/or has no data associated with it.

Examples
Good
curl "https://host.io/api/web/facebook.com?token=$TOKEN"
{
    "domain": "facebook.com",

    # Position in host.io 10M domains ranking, https://host.io/rankings
    "rank": 2,
    
    # URL we scraped the data from
    "url": "https://www.facebook.com/",

    # Actual IP we scraped the data from
    "ip": "157.240.11.35",
    
    # Date we scraped the data
    "date": "2020-08-26T17:39:17.981Z",

    # Length of the HTML content we scraped
    "length": 160817,
    
    # Encoding of the scraped data
    "encoding": "utf8",

    # Scraped copyright notice
    "copyright": "Facebook © 2020",

    # HTML title
    "title": "Facebook - Log In or Sign Up",

    # HTML meta description
    "description": "Create an account or log into Facebook. Connect with friends, family and other people you know. Share photos and videos, send messages and get updates.",
    
    # Domains of links on the homepage
    "links": [
        "messenger.com",
        "oculus.com"
    ]
}
Bad
curl "https://host.io/api/web/example.example?token=$TOKEN"
{
  "error": "No details found for example.example"
}

/api/dns/:domain

Description

Get all the DNS records stored for a domain.

Currently supported records are:

  • A (IPv4 address)
  • AAAA (IPv6 address)
  • MX (mailserver)
  • NS (nameserver)
Errors

Returns the HTTP 404 status code as well as an error message in JSON format if the domain is invalid and/or has no data associated with it.

Examples
Good
curl "https://host.io/api/dns/facebook.com?token=$TOKEN"
{
    "domain": "facebook.com",
    "a": [
        "157.240.3.35"
    ],
    "aaaa": [
        "2a03:2880:f101:83:face:b00c:0:25de"
    ],
    "mx": [
        "10 smtpin.vvv.facebook.com."
    ],
    "ns": [
        "a.ns.facebook.com.",
        "b.ns.facebook.com."
    ]
}
Bad
curl "https://host.io/api/dns/example.example?token=$TOKEN"
{
    "error": "No details found for example.example"
}

/api/related/:domain

Description

Get a count of the number of related domains for all supported lookups we offer. See /api/domains/:field for a full list of fields, and details on how to get the list of related domains.

Errors

Returns the HTTP 404 status code as well as an error message in JSON format if the domain is invalid and/or has no data associated with it.

Examples
curl "https://host.io/api/related/google.com?token=$TOKEN"
{
    "ip": [
        {
            "value": "172.217.14.238",
            "count": 293
        },
        {
            "value": "216.58.193.68",
            "count": 71
        }
    ],
    "redirects": [
        {
            "value": "google.com",
            "count": 629989
        }
    ],
    "backlinks": [
        {
            "value": "google.com",
            "count": 17314912
        }
    ],
    "asn": [
        {
            "value": "AS15169",
            "count": 16219992
        }
    ]
}

/api/full/:domain

Description

A single endpoint that includes the data from /api/web, /api/dns, /api/related and IPinfo.

Errors

Returns the HTTP 404 status code as well as an error message in JSON format if the domain is invalid and/or has no data associated with it.

Examples
Good
curl "https://host.io/api/full/google.com?token=$TOKEN"
{
    "domain": "google.com",
    "dns": {
        "domain": "google.com",
        "a": [
            "172.217.14.238"
        ],
        "aaaa": [
            "2607:f8b0:400a:803::200e"
        ],
        "mx": [
            "10 aspmx.l.google.com.",
            "20 alt1.aspmx.l.google.com.",
            "30 alt2.aspmx.l.google.com.",
            "40 alt3.aspmx.l.google.com.",
            "50 alt4.aspmx.l.google.com."
        ],
        "ns": [
            "ns1.google.com.",
            "ns2.google.com.",
            "ns3.google.com.",
            "ns4.google.com."
        ]
    },
    "ipinfo": {
        "216.58.193.68": {
            "city": "Seattle",
            "region": "Washington",
            "country": "US",
            "loc": "47.6062,-122.3321",
            "postal": "98111",
            "timezone": "America/Los_Angeles",
            "asn": {
                "asn": "AS15169",
                "name": "Google LLC",
                "domain": "google.com",
                "route": "216.58.192.0/22",
                "type": "business"
            }
        },
        "2607:f8b0:400a:803::200e": {
            "city": "Mountain View",
            "region": "California",
            "country": "US",
            "loc": "37.4056,-122.0775",
            "postal": "94043",
            "timezone": "America/Los_Angeles",
            "asn": {
                "asn": "AS15169",
                "name": "Google LLC",
                "domain": "google.com",
                "route": "2607:f8b0:400a::/48",
                "type": "business"
            }
        }
    },
    "web": {
        "domain": "google.com",
        "rank": 1,
        "url": "https://www.google.com/?gws_rd=ssl",
        "ip": "216.58.193.68",
        "date": "2019-11-25T18:58:31.543Z",
        "length": 205694,
        "server": "gws",
        "encoding": "utf8",
        "title": "Google",
        "description": "Search the world's information, including webpages, images, videos and more. Google has many special features to help you find exactly what you're looking for.",
        "links": [
            "about.google"
        ]
    },
    "related": {
        "ip": [
            {
                "value": "172.217.14.238",
                "count": 293
            },
            {
                "value": "216.58.193.68",
                "count": 71
            }
        ],
        "redirects": [
            {
                "value": "google.com",
                "count": 629989
            }
        ],
        "asn": [
            {
                "value": "AS15169",
                "count": 16219992
            }
        ],
        "backlinks": [
            {
                "value": "google.com",
                "count": 17314912
            }
        ],
        "mx": [
            {
                "value": "google.com",
                "count": 11624298
            }
        ],
        "ns": [
            {
                "value": "google.com",
                "count": 12221
            }
        ]
    }
}
Bad
curl "https://host.io/api/domains/full/example.example?token=$TOKEN"
{
    "error": "No details found for example.example"
}

/api/domains/:field/:value

Get all domains associated with :field, and a count of the total. The :value should be according to the :field and not necessarily a domain. Supported fields:

Field Descr Example
ip IP address (v4 or v6) 8.8.8.8
ns DNS Nameserver (NS) record (root domain) google.com
mx DNS Mailserver (MX) record (root domain) google.com
asn ASN AS15169
backlinks Domains that include a link to the domain on their homepage google.com
redirects Domains that redirect to the domain from their homepage google.com
adsense Domains that include an adsense ID on their homepage pub-1556223355139109
facebook Domains linking to the Facebook social media handle on their homepage spacenewsx
twitter Domains linking to the Twitter social media handle on their homepage elonmusk
instagram Domains linking to the Instagram social media handle on their homepage chadwickboseman
gtm Domains having the google tag manager ID on their homepage GTM-544JFM
googleanalytics Domains that include a googleanalytics ID on their homepage UA-55552418
email Domains that include an email address on their homepage admin@google.com

Results are limited to a maxmimum of 1000 per page, and a maximum of 10 million total results.

Also see /api/related/:domain, which returns the count of related domains and the associated values for a domain.

Parameters
  • limit: Must be one of 0, 1, 5, 10, 25, 100, 250, or 1000. Default is 25.
  • page: The page of data to view, 0-indexed. Default is 0. Pagination takes into account the limit.
Errors

Returns the HTTP 404 status code as well as an error message in JSON format if the domain is invalid and/or has no data associated with it, or if the limit/page combination is out-of-bounds.

Examples
Good
curl "https://host.io/api/domains/googleanalytics/UA-61330992?limit=5&token=$TOKEN" 
{
    "googleanalytics": "UA-61330992",
    "total": 10,
    "domains": [
        "minilex.fi",
        "minilex.at",
        "minilex.sk",
        "minilex.se",
        "minilex.be"
    ]
}
curl "https://host.io/api/domains/email/office@ssa-vending.com?limit=5&token=$TOKEN"
{
    "email": "office@ssa-vending.com",
    "total": 3,
    "domains": [
        "ssa-vending.com",
        "schank-service.com",
        "ssa-softdrinks.com"
    ]
}
curl "https://host.io/api/domains/ns/google.com?limit=5&page=5&token=$TOKEN"
{
    "ns": "google.com",
    "page": 5,
    "total": 12221,
    "domains": [
        "google.com.eg",
        "google.co.th",
        "google.nl",
        "google.co.ve",
        "google.co.za"
    ]
}
curl "https://host.io/api/domains/twitter/elonmusk?limit=5&token=$TOKEN"
{
    "twitter": "elonmusk",
    "total": 192,
    "domains": [
        "muskx.online",
        "beyondgoodandevil.org",
        "enn0.de",
        "numerocivico.com",
        "jadeedarabia.com"
    ]
}
Bad (invalid UA)
curl "https://host.io/api/domains/googleanalytics/UA-FOO?token=$TOKEN"
{
    "error": "No details on 'googleanalytics' found for UA-FOO"
}
Bad (invalid limit/page combo)
curl "https://host.io/api/domains/googleanalytics/UA-61330992?limit=250&page=100&token=$TOKEN"
{
    "error": "No details on 'googleanalytics' found for UA-61330992"
}
Bad (invalid :value)
curl "https://host.io/api/domains/gtm/google.com?token=$TOKEN"
{
    "error": "No details on 'gtm' found for google.com"
}