Welcome

Hello and welcome to the API documentation for all JsonWhois services. Should you experience any issues in consumption our APIs or you encounter any unexpected behaviour please get in touch with us. 

https://api.jsonwhois.io/

Authentication

To authenticate your request please pass your API key to the API end point in a similar fashion to the example provided to the right. Your request is now authenticated and logged in your API call log. 

https://api.jsonwhois.io/?key=YOUR_KEY_HERE

Response codes

The JsonWhois API uses standard HTTP response codes to communicate the result of an API call. We have endeavoured to match the original meaning of the HTTP response code to our adopted meaning, however the meaning may not always be clear. In such an eventuality please use the below table to understand the API response codes you receive.

Codes
  • 200 Processed

    The command was processed successfully.

  • 422 Unprocessable

    Well formatted request however some technical issue is preventing the serving of the request, e.g. an unresponsive WHOIS server

  • 400 Command unknown

    The end-point you have sent the request to is not valid (for example, the end point should be /whois or /screenshot)

  • 405 Command invalid

    The HTTP request method used is not compatible with the selected end-point. This can occur when using POST rather than GET for example.

  • 409 Command malformed

    The request has been incorrectly constructed. This can occur when omitting required parameters or providing them in the wrong type.

  • 401 Unauthorized

    The request was not authorised. This can occur when using an incorrect key, if the server IP is not on the account whitelist, or if the account is banned.

  • 402 Billing

    The request was refused due to a billing issue with the associated account.

  • 500 Internal Server Error

    The client did everything correctly, but we've had an internal issue.

Client side libraries

Below you can find a growing list of open source libraries designed to make your consumption of the JsonWhois API quick and easy.

We are always looking to expand into more languages and we'd love to do it with the help of our community, you can help-out by contributing to our existing repositories on GitHub or asking us to start a new one for a language of your desire. All users who contribute to our community libraries will be rewarded by our everlasting gratitude and, as if that wasn't enough, free account credit!


Language Repository
PHP https://github.com/JsonWhois/WHOIS-API-PHP
NodeJS https://github.com/JsonWhois/WHOIS-API-NODE-JS
Python https://github.com/JsonWhois/WHOIS-API-PYTHON

Domain Whois lookup

This end-point accepts a domain as the argument and performs a live Whois query.

Parameter Description
domain The domain name to lookup. 
curl 'https://api.jsonwhois.io/whois/domain?key=YOUR_KEY_HERE&domain=google.com'
- -> 

use JsonWhois\Adapter\Domain\Whois as DomainWhois;

# set key for demo
define('JSONWHOISIO_PRIV_KEY', 'REPLACE WITH YOUR KEY HERE');

# set to true to ignore TLS errors (use only for testing)
define('JSONWHOISIO_IGNORE_CA', true);

# domain for which to query the WHOIS API
$domain = 'google.com';

# Create a new instance of DomainWhois
# This is not required with each call, only the first
$DomainWhois = new DomainWhois(JSONWHOISIO_PRIV_KEY);

# set the domain for the query
$DomainWhois->setPayload($domain);

# Perform the query and store the resulting object 
$Result = $DomainWhois->run();

# check for successful execution
if (!$Result->isSuccessful()) {
   # query failed, print the reason
   echo 'Lookup failed (' . $Result->getStatusCode() . '): ' . $Result->getStatusMessage();
} else {
   # get the result of the successful query as an array (default) 
   $dataArray = $Result->getDataArray();

   echo 'Expiry date (array): ' . $dataArray['expires'];
}
                              

                            

{  
   "result":{  
      "name":"google.com",
      "created":"1997-09-15 07:00:00",
      "changed":"2015-06-12 17:38:52",
      "expires":"2020-09-14 00:00:00",
      "dnssec":"unsigned",
      "registered":true,
      "status":[  
         "clientUpdateProhibited (https:\/\/www.icann.org\/epp#clientUpdateProhibited)",
         "clientTransferProhibited (https:\/\/www.icann.org\/epp#clientTransferProhibited)",
         "clientDeleteProhibited (https:\/\/www.icann.org\/epp#clientDeleteProhibited)",
         "serverUpdateProhibited (https:\/\/www.icann.org\/epp#serverUpdateProhibited)",
         "serverTransferProhibited (https:\/\/www.icann.org\/epp#serverTransferProhibited)",
         "serverDeleteProhibited (https:\/\/www.icann.org\/epp#serverDeleteProhibited)"
      ],
      "nameservers":[  
         "ns3.google.com",
         "ns4.google.com",
         "ns2.google.com",
         "ns1.google.com"
      ],
      "contacts":{  
         "owner":[  
            {  
               "handle":null,
               "type":null,
               "name":"Dns Admin",
               "organization":"Google Inc.",
               "email":"dns-admin@google.com",
               "address":"Please contact contact-admin@google.com, 1600 Amphitheatre Parkway",
               "zipcode":"94043",
               "city":"Mountain View",
               "state":"CA",
               "country":"US",
               "phone":"+1.6502530000",
               "fax":"+1.6506188571",
               "created":null,
               "changed":null
            }
         ],
         "admin":[  
            {  
               "handle":null,
               "type":null,
               "name":"DNS Admin",
               "organization":"Google Inc.",
               "email":"dns-admin@google.com",
               "address":"1600 Amphitheatre Parkway",
               "zipcode":"94043",
               "city":"Mountain View",
               "state":"CA",
               "country":"US",
               "phone":"+1.6506234000",
               "fax":"+1.6506188571",
               "created":null,
               "changed":null
            }
         ],
         "tech":[  
            {  
               "handle":null,
               "type":null,
               "name":"DNS Admin",
               "organization":"Google Inc.",
               "email":"dns-admin@google.com",
               "address":"2400 E. Bayshore Pkwy",
               "zipcode":"94043",
               "city":"Mountain View",
               "state":"CA",
               "country":"US",
               "phone":"+1.6503300100",
               "fax":"+1.6506181499",
               "created":null,
               "changed":null
            }
         ]
      },
      "registrar":{  
         "id":"292",
         "name":"MarkMonitor, Inc.",
         "email":"abusecomplaints@markmonitor.com",
         "url":"http:\/\/www.markmonitor.com",
         "phone":"+1.2083895740"
      }
   }
}

IP address Whois lookup

This end-point accepts an IP address as the argument and performs a live lookup.

Parameter Description
ip_address The domain name to lookup. 
curl 'https://api.jsonwhois.io/whois/ip?key=YOUR_KEY_HERE&ip_address=18.97.14.86'

use JsonWhois\Adapter\IP\Whois as IpWhois;

# set key for demo
define('JSONWHOISIO_PRIV_KEY', 'REPLACE WITH YOUR KEY HERE');

# set to true to ignore TLS errors (use only for testing)
define('JSONWHOISIO_IGNORE_CA', true);

# ip for which to query the WHOIS API
$ip = '8.8.8.8';

# Create a new instance of IpWhois
# This is not required with each call, only the first
$IpWhois = new IpWhois(JSONWHOISIO_PRIV_KEY);

# set the ip for the query
$IpWhois->setPayload($ip);

# Perform the query and store the resulting object 
$Result = $IpWhois->run();

# check for successful execution
if (!$Result->isSuccessful()) {
   # query failed, print the reason
   echo 'Lookup failed (' . $Result->getStatusCode() . '): ' . $Result->getStatusMessage();
} else {
   # get the result of the successful query as an array (default) 
   $dataArray = $Result->getDataArray();
   
   echo 'Created date (array): ' . $dataArray['created'] . '
';
}
                              

                            

{  
   "result":{  
      "name":"8.8.8.8",
      "created":"2014-03-14 00:00:00",
      "changed":"2014-03-14 00:00:00",
      "status":"Reallocated",
      "contacts":{  
         "owner":[  
            {  
               "handle":"GOGL",
               "type":null,
               "name":null,
               "organization":"Google Inc.",
               "email":null,
               "address":"1600 Amphitheatre Parkway",
               "zipcode":"94043",
               "city":"Mountain View",
               "state":"CA",
               "country":"US",
               "phone":null,
               "fax":null,
               "created":"2000-03-30 00:00:00",
               "changed":"2017-01-28 00:00:00"
            }
         ],
         "tech":[  
            {  
               "handle":"ZG39-ARIN",
               "type":null,
               "name":"Google Inc",
               "organization":null,
               "email":"arin-contact@google.com",
               "address":null,
               "zipcode":null,
               "city":null,
               "state":null,
               "country":null,
               "phone":"+1-650-253-0000",
               "fax":null,
               "created":null,
               "changed":null
            }
         ],
         "abuse":[  
            {  
               "handle":"ABUSE5250-ARIN",
               "type":null,
               "name":"Abuse",
               "organization":null,
               "email":"network-abuse@google.com",
               "address":null,
               "zipcode":null,
               "city":null,
               "state":null,
               "country":null,
               "phone":"+1-650-253-0000",
               "fax":null,
               "created":null,
               "changed":null
            }
         ]
      },
      "network":{  
         "inetnum":"8.8.8.0 - 8.8.8.255",
         "name":"LVLT-GOGL-8-8-8",
         "handle":"NET-8-8-8-0-1"
      }
   }
}

Domain availability check

This end-point accepts a domain as the argument and performs an availability check and returns the status of the domain as a boolean value.

Parameter Description
domain The domain name for which to check availability. 
curl 'https://api.jsonwhois.io/availability?key=YOUR_KEY_HERE&domain=emailrecon.com'

use JsonWhois\Adapter\Domain\Availability as DomainAvailability;

# set key for demo
define('JSONWHOISIO_PRIV_KEY', 'REPLACE WITH YOUR KEY HERE');

# set to true to ignore TLS errors (use only for testing)
define('JSONWHOISIO_IGNORE_CA', true);

# domain for which to query the WHOIS API
$domain = 'google.com';

# Create a new instance of DomainAvailability
# This is not required with each call, only the first
$DomainAvailability = new DomainAvailability(JSONWHOISIO_PRIV_KEY);

# set the domain for the query
$DomainAvailability->setPayload($domain);

# Perform the query and store the resulting object 
$Result = $DomainAvailability->run();

# check for successful execution
if (!$Result->isSuccessful()) {
   # query failed, print the reason
   echo 'Lookup failed (' . $Result->getStatusCode() . '): ' . $Result->getStatusMessage();
} else {
   # get the result of the successful query as an array (default) 
   $dataArray = $Result->getDataArray();
   
   echo 'Is Available (array): ' . ($dataArray['is_available'] ? 'Yes' : 'No') . '
';
}
                              

                            

{  
   "is_available":false
}

Screenshot

This end-point accepts a URL as the argument and creates a screenshot of the website located at that address. The result of this operation is returned as a base64 encoded image wrapped in a json object.

Parameter Description
url The web address of the page to render and captured.
file_type
Optional 		The desired file type of the screenshot. Choose between jpeg and png. Defaults to 1920.
width
Optional 		The width of the client used to render the webpage, specified in pixels. Defaults to 1080.
transparent
Optional 		Removes the default white background of the rendering engine. Any content on the page without a background colour will be rendered transparent (alpha 0). Set to "true" or 1 to enable, set to "false" or 0 to disable. Only available on PNG images. Defaults to "false".
quality
Optional 		Specify the quality of the screen grab on a scale between 1 and 100. The higher the number the better quality the image. Only available on jpeg files. Defaults to 85.
full_page
Optional 		Set to "false" or 0 to capture only the above the fold content. Where above the fold is defined by the box specified in the width & height parameters. Set to "true" or 1 to capture the entire page. Only available with PNG and jpeg export types. Defaults to "false".
request_timeout
Optional 		The time expressed in seconds to wait before the screenshot is taken (even though resources have been loaded), defaults to 1 second. Set to 0 to take the screenshot as soon as the network becomes idle. 
curl 'https://api.jsonwhois.io/screenshot?key=YOUR_KEY_HERE&url=example.com&width=1200&height=800'


use JsonWhois\Adapter\Browser\Screenshot as BrowserScreenshot;

# set key for demo
define('JSONWHOISIO_PRIV_KEY', 'REPLACE WITH YOUR KEY HERE');

# set to true to ignore TLS errors (use only for testing)
define('JSONWHOISIO_IGNORE_CA', true);

# domain for which to make a screenshot
$domain = 'google.com';

# Create a new instance of BrowserScreenshot
# This is not required with each call, only the first
$BrowserScreenshot = new BrowserScreenshot(JSONWHOISIO_PRIV_KEY);

$width = 1200;
$height = 900;
# set the domain for the query
$BrowserScreenshot->setPayload($domain, $width, $height);

# Perform the query and store the resulting object 
$Result = $BrowserScreenshot->run();

# check for successful execution
if (!$Result->isSuccessful()) {
   # query failed, print the reason
   echo 'Lookup failed (' . $Result->getStatusCode() . '): ' . $Result->getStatusMessage();
} else {
   # get the result of the successful query as an array (default) 
   $dataArray = $Result->getDataArray();
   
   echo '<img src="' . $dataArray['prefix'] . $dataArray['base64'] . '" />';
}
                              

                            

{
   "base64": "iVBORw0KGgoAAAANSUhEUgAABLAAAAMgCAYAAAAz4JsCAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEwAACxMBAJqcGAAAIABJREFUeJzs3Xl4FFXa9/FfJ4QkhCxCgIAigUDYZVM2BUUIguOoIKKyM0IEZGdYnBEYotFHBYQBUUFAGYwCj4OIgAqKKEscmQFGEBBCAAEF2RKUkJDl/cMn/abp6qS60yFF+vu5Li7N6VOn7rNUpftOVbXt4sX0PAEAAAAAAAAW5VfaAQAAAAAAAACFIYEFAA ... ACANAELAAAAgDQBCwAAAIA0AQsAAACANAELAAAAgDQBCwAAAIC0/wBqRycyXwTWgAAAAABJRU5ErkJggg==",
   "prefix": "data:image\/png;base64,"
}