DNS Lookup API User Guide

A domain has a number of records associated with it, a DNS server can be queried to determine the IP address of the primary domain (A record), mail servers (MX records), DNS servers (NS nameservers) and other items such as SPF records (TXT records).

WhoisXmlApi.com provides RESTful APIs. It is designed for server-to-server communication between your system and the WhoisXmlApi.com network using standard HTTP or HTTPS protocols. Query responses are delivered in either XML or JSON format based on your requests which are made via GET/POST methods.

To get started you need a developer's account with WhoisXmlApi.com. Authentication is required each time in order to use the API. The first 500 DNS lookup calls are complimentary when you register for a free developer account.

API status

You can check the API's current performance and availability status on the API Status Page.

Making a Call to DNS Lookup API Web Service

Use the following URL:

https://www.whoisxmlapi.com/whoisserver/DNSService?domainName=google.com&type=1&username=xxxxx&password=xxxxx

Supported input parameters

Parameters	Values
domainName	required, the domain for which DNS data is requested
username	required unless ApiKey authentication is used, your account username
password	required unless ApiKey authentication is used, your account password; *make sure it is URL-encoded if it contains special characters (&, %, etc.)**
requestObject	required unless password authentication is used, encoded user identifier for ApiKey authentication
digest	required unless password authentication is used, ApiKey access token
type	required, dns type: A, NS, SOA, MX, etc.; you can specify multiple comma-separated values, e.g., A,SOA,TXT; all records can be retrieved with type=_all
outputFormat	XML \| JSON (defaults to XML)
callback	a javascript function used when outputFormat is JSON; this is an implementation known as JSONP which invokes the callback on the returned response

Supported DNS Types

We support around fifty DNS types. You can use type codes or names from the table below:

Name	Code	Name	Code
A	1	GPOS	27
NS	2	AAAA	28
MD	3	LOC	29
MF	4	NXT	30
CNAME	5	EID	31
SOA	6	NIMLOC	32
MB	7	SRV	33
MG	8	ATMA	34
MR	9	NAPTR	35
NULL	10	KX	36
WKS	11	CERT	37
PTR	12	A6	38
HINFO	13	DNAME	39
MINFO	14	APL	42
MX	15	DS	43
TXT	16	SSHFP	44
RP	17	IPSECKEY	45
AFSDB	18	RRSIG	46
X25	19	NSEC	47
ISDN	20	DNSKEY	48
RT	21	DHCID	49
NSAP	22	NSEC3	50
NSAP_PTR	23	NSEC3PARAM	51
SIG	24	TLSA	52
KEY	25	ANY	255
PX	26	DLV	32769

Usage of HTTP & HTTPS

You can use both http and https to make the API query. With HTTPs the connection would be more secure but slightly slower.

Sample code for making a query to DNS Lookup API Web Service

You may view examples of querying DNS Lookup API by clicking on the following links or visiting our GitHub page

User password authentication

C# code: example, full project

Java code: example, full project

Javascript code: JSONP

Node.js code: example

Perl code: example

PHP code: example

PowerShell code: example

Python code: example

Ruby code: example

API key authentication

C# code: example, full project

Java code: example, full project

Javascript code: JSONP

Node.js code: example

Perl code: example

PHP code: example

PowerShell code: example

Python code: example

Ruby code: example

Usage Limits

The maximum number of requests per second is 1. In case that the limit is breached (either from single IP address or from multiple IPs), you will be penalized with the 30 second ban. That ban includes IPs that were used at the time of the offence, and includes all following IPs (based on username from additional requests) used during the ban time.

Query Account Balance Information

In order to query your account balance, use the following URL:

https://www.whoisxmlapi.com/accountServices.php?servicetype=accountbalance&username=xxxxx&password=xxxxx

Supported input parameters

Parameters	Values
servicetype	required, type of service; in this case, "accountBalance"
username	required, your account username
password	required, your account password; *make sure it is URL-encoded if it contains special characters (&, %, etc.)**
output_format	XML \| JSON (defaults to XML)

You will receive a response with your account balance.

Authentication

Password authentication

This method uses your account's username and password to authenticate with the web service. Just pass your credentials as query string parameters (username, password).

API key authentication

Generate access tokens providing your API and secret keys to make DNS Lookup API calls without sending your username and password. These tokens will need to be included as part of the request URL (requestObject, digest). Please, note that all tokens expire after 5 minutes and will have to be regenerated. Access the API Key Management section of your account to create your keys (make sure the key you're using is marked as active).

TLDs Supported

We support thousands of TLDs, both gTLDs and ccTLDS. You can see the entire list here.

Sample Output

XML

JSON

Printable guide

You can also download the PDF version of this guide.