login
 
WhoAPI
Plans & Pricing Blog Support
 

API Documentation v2.1

The WhoAPI is a RESTful based API. Communication is made through a normal HTTP requests.

Requests are made as strings using HTTP GET method. All outputs are provided as a JSON formatted responses.

Authentication

Authentication is needed in order to use the API, and for this a WhoAPI account is required. You'll need your API key every time you make a request. You have the option to limit API requests by a certain IP addresses in your account settings.

You can find your unique API key inside the "My account" section on the left once you register.

Setting up input request

GET requests should provide their parameters as a query string, part of the URL.

GET	
http://api.whoapi.com/?domain=whoapi.com&r=whois&apikey=YOUR_API_KEY

We suggest you test the API requests via the API console before you start your implementation.

» http://api.whoapi.com/console/

When you make an API request, you have to specify the value of these parameters:

query parameter description
domain full domain name, including the tld e.g. whoapi.com
r type of the request, parameters explained below
apikey your private unique api key
rr * optional returns your request in json result (useful for testing your scripts)
ip * optional ip address for API functions like ping and tracert, not mandatory
port * optional port number, additionial field for API function pingservice
fullurl * optional some functions allow full URL query e.g. ranks
node * beta force API to use specific WhoAPI node (for beta testers)

Basic description of input parameters

Output data depends on the chosen request type.

Request (with number of queries per minute) Free plan Basic Standard Pro
hostname
Get domain/server hostname
10 50 100 200
geo
Domain or IP geolocation
10 50 100 200
meta
Domain content meta tags: title & description
10 50 100 200
dnszone
Complete DNS Zone record in a structured JSON
10 50 100 200
cert
Detailed domain certificate information
10 50 100 200
social
Availability status on popular social networks
5 50 100 200
tracert
Detailed network route to your domain/ip from all our nodes
5 50 100 200
searchengines
Domain results on popular search engines
5 50 100 200
screenshot
Website screenshot in actual full vertical size and a thumbnail
5 10 50 100
ping
Ping request time from all our nodes and overall result of server availability
5 50 100 200
pingservice
Same as above + a certain port on the server
5 50 100 200
blacklist
Check if domain IP is listed on all popular mail blacklists
1 50 100 200
ranks
Domain rank on popular systems like Google Pagerank™
5 10 50 100
taken
Check domian availability for registration
5 50 100 200
whois
Structured WHOIS data
1 5 10 50
myaccount
Client API high-usage limits & active plan details
unlimited unlimited unlimited unlimited

The Content-Type header of the response is set to "application/json; charset=utf-8".
Output is compressed with gzip.

WhoAPI functions

Click to open a more detailed view with instructions how to use the function and the output.

top api functions server functions content functions client functions
taken ping meta myaccount
blacklist pingservice searchengines  
whois tracert screenshot  
ipwhois hostname    
social dnszone    
ranks geo    
cert      

Default Output Variables

You will always get these fields in the response:

output parameter description
status status code for your request, check all the codes here
status_desc description of the status in the plain english

Let's make an example request: (check domain availability for whoapi.com)

http://api.whoapi.com/?domain=whoapi.com&r=taken&apikey=demokey

Output in JSON format:

{
    "status":"0",
    "status_desc":"Request successful!",
    "taken": "1",
    "method": "whois",
    "ip": "78.47.103.206"
}

Result is stored in the "taken" value which is in this case "1", same as "Domain not available for registration". Each function has a set of it's own resulting variables.

API Request Limits

All WhoAPI plans are unlimited but with high-usage limits to avoid degradation of the overall client experience. These limits protect the system from poorly coded scripts and misuse, not to restrict you as a client.

You can check the limits by making a free API call: function: myaccount

API Status Codes

status code description
0 Request successful!
1 Invalid characters in domain name.
2 Use of double dot in domain name.
3 Domain name starting or ending with dash or dot.
4 TLD does not exist.
5 Too many characters in domain name (without TLD), maximum length is 64.
6 Too many characters in TLD.
7 TLD not supported by the API.
8 Missing request type in 'r' parameter.
9 Invalid request type in 'r' parameter.
10 API key invalid.
11 Invalid characters in 'port' parameter.
12 Invalid API account.
13 Account suspended.
14 Account canceled.
15 IP not whitelisted in Account settings.
16 Too many tries, your IP has been blocked for a minute.
17 Query limit exceeded.
18 Query high usage limit exceeded.
19 Missing domain name in 'domain' parameter.
20 Invalid IP address in 'ip' parameter.
21 Invalid 'fullurl' parameter, must be fully qualified URI.
22 Invalid node data, only numeric characters allowed.
23 Missing 'port' parameter.
24 Missing valid TLD in domain name.
25 Unknown output type.
26 Timeout getting the result from a node.
27 Fatal error detected in result from a node.
28 Unknown error detected in result from a node.
29 Cannot resolve domain name, IP needed.
30 Problem with the WHOIS server, please try again later.
31 WHOIS limit reachd for used WhoAPI node. Please repeat a request to get the result from a different node.
32 Cannot resolve domain availability by using the requested method.


Twitter Facebook Google+ Copyright © 2014 WhoAPI Inc., Smart Queries Ltd.
444 Castro Street, Suite 1200, 94041 CA, Mountain View, United States.