WhoisAPI Documentation V 2.3

XML API Documentation
Version 2.3

All information contained herein is confidential and proprietary information of Name Intelligence, Inc. Use of the API and this documentation is only for developer that have agreed to API terms of service.

For support please issue a support ticket to http://support.domaintools.com/. Include your username.

Last Modified: November 28 2006

Documentation Index

1. General Overview

2. Connecting to Name Intelligence API server

3. Application Node

appname
version
partner
key
customer_ip
4. Applications:

1) name_spinner
2) search_engine
3) bulk_check
4) areacode_location
5) ip_location

5. Request and Response Objects

q (Query)
b (Bulk Query)
rows
bh (Block Hyphens)
bn (Block Numbers)
bc (Block Count)
left
right
ordered
pool
page
exactfirst
intellisearch
f7
did_you_mean
errlev
more
time
ext
extn
page_current
page_min
page_max
page_extreme
records_returned
records_min
records_max
records_extreme
querytime
d
id
n
s

6. Error nodes V. 2

1). Errors Messages for all Version 2 code.

1. General Overview

The XML request feature allows a partner’s site to grab search results from the whois API search engine or other dynamic content repositories inside Name Intelligence.

There are several applications inside Name Intelligence but the most commonly used is the name_spinner application. Due to on going improvements in the system we freeze application by version number. So for example if a system is designed to operate with our search_engine application under version 2 it will always expect the same input and output. As new versions become available they will be announced and documented. Partners are encouraged to upgrade, however their current systems will not be effected.

Please note: In the request all variable names should use lowercase.

General Format:
The general format for all XML documents is the same. All documents have four nodes: application, request, response, and errors nodes. The application node maps to an application on the Name Intelligence side that fulfills the partner’s request. The general format follows the pattern below:

<WHOISAPI>
<APPLICATION>
  <element1>value1</element1>
  <element2>value2</element2>
</APPLICATION>
<REQUEST>
  <element1>value1</element1>
  <element2>value2</element2>
</REQUEST>
<REPONSE>
  <element1>value1</element1>
  <element2>value2</element2>
</REPONSE>
<ERRORS>
  <element1>value1</element1>
  <element2>value2</element2>
</ERRORS>
</WHOISAPI>

2. Connecting to the Name Intelligence API server

The API is driven via a HTTP GET request on the standard port 80 of a web server. The API is not intended for direct access via a partner’s retail customers. But we do allow a partner to allow sub-accounts for larger resellers to directly query us (please contact sales for more information). We recommend that in most cases the partner proxy all traffic so they can log all requests.

Requests MUST be sent using HTTP GET rather than HTTP POST. All HTTP POST requests will return an error code in the response. To protect access to our API server we can lock down IP addresses to users so that only they may connect. By default we don't lock down accounts, but this can be enabled via the control panel.

API Interface: engine.whoisapi.com/api.xml

Query Cleaning: The whoisapi.com engine only accepts plain ASCII (text) requests/streams. Encoded streams are not acceptable at this time. All non-ASCII characters will be converted or eliminated automatically (warning/error message may be given). Also note that “www.”, “.com”, “http://”, and other garbage will be automatically striped away from query strings so that user receive a more pleasant result.

3. Application Node

The Application parameters in your HTTP query tell our API interface which application to handle your request. These parameters also authenicate use of the server.

All applications documented in this manual are version 2.

Parameters:

appname
version
partner
key
customer_ip
Query (example):

/api.xml?appname=search_engine&version=2&partner=nameintel&key=12345-12345-12345-12345-12345&customer_ip=100.200.155.230 ... more parameters should follow

Response (Example):
The application parameters will be repeated back in the application response node.

<APPLICATION>
<APPNAME>search_engine</APPNAME>
<VERSION>2</VERSION>
<PARTNER>nameintel</PARTNER>
<KEY>12345-12345-12345-12345-12345</KEY>
<CUSTOMER_IP>100.200.155.230</CUSTOMER_IP>
<APPLICATION>

Application Objects:

Variable Default Allowed Description
APPNAME {Application Requested} Application Title
Setting the Application handler is the most important step.
ERRORS 501 – Application APPNAME not named or not found.

Variable Default Allowed Description
VERSION [0-9]+ Application Version
By setting the version number you will be able to access different versions of the application. We strongly recommend using the latest version, we only offer support on that.
ERRORS 502 – VERSION value not in range or is null.

Variable Default Allowed Description
PARTNER {Partner ID} Assigned by NI
Directs the channel to debit a partner’s account
ERRORS 511 – PARTNER value not in range or is null.
512 – Account is locked.
513 – Contact Name Intelligence regarding your account.

Variable Default Allowed Description
KEY [0-9]{5}-[0-9]{5}-[0-9]{5}-[0-9]{5}-[0-9]{5} Access Key
Password for accessing the account. If registered IPs is turned off KEY is required. Optional parameter if partner’s server IPs are registered.
ERRORS 504 – KEY value not in range or is null.

Variable Default Allowed Description
CUSTOMER_IP [0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3} IP address of partner's end-user
Pass along the end customer’s IP address so that Name Intelligence can track down abuse on the partner’s site. We can not assist in controlling rouge abusers on the partner’s site if we don't have a way of tracking them. If we have an abuse case on a partner's site we will help in blocking the abuser. Abuse does happen and we have a lot of experience in blocking automated scripts. You will not be charged for abusive end-users provided that Name Intelligence is working with you in stopping the abuse. If you suspect abuse consult your service rep immediately.
ERRORS 505– CUSTOMER_IP value not in range.

4. Applications

1) name_spinner
Parameters expected:

q (Query)
rows
bc (Block Count)
adult (word filter)
ext

XML Objects returned by NI:

extn
querytime
universe
e
d
id
n & e_n
s & e_s
Query (example):

/api.xml?application=name_spinner&version=4&partner=nameintel&
key=12345-12345-12345-12345-12345&customer_ip=100.200.155.230&
q=domain&rows=20&bc=n&ext=COM|NET|ORG|INFO|BIZ|US

Request Object sent back from NI (example):

<REQUEST>
  <Q>apple</Q>
  <ROWS>20</ROWS>
  <BC>n</BC>
  <ADULT>auto</ADULT>
</REQUEST>

Response Object sent back from NI (example):

<RESPONSE>
  <EXTN>COM|NET|ORG|INFO|BIZ|US</EXTN>
  <QUERYTIME>0.001018</QUERYTIME>
  <E>
   <E_N>apple</E_N>
   <E_S>xxxxxx</E_S>
  </E>
  <D>
   <ID>1</ID>
   <N>applepie</N>
   <S>xqqqqq</S>
  </D>
  <D>
   <ID>2</ID>
   <N>appletreepie</N>
   <S>xqqqqq</S>
  </D>
  .....
  <D>
   <ID>20</ID>
   <N>applescottpie</N>
   <S>xqqqqq</S>
  </D>
</RESPONSE>

2) search_engine
Parameters expected:

q (Query)
rows
bh (Block Hyphens)
bn (Block Numbers)
bc (Block Count)
left
right
ordered
pool
page
exactfirst
intellisearch
f7
time
ext

XML Objects returned by NI:

extn
did_you_mean
page_current
page_min
page_max
page_extreme
records_returned
records_min
records_max
records_extreme
querytime
d
id
n
s
Query (example):

/api.xml?application=search_engine&version=2&partner=nameintel&
key=12345-12345-12345-12345-12345&customer_ip=100.200.155.230&
q=domain&rows=20&bn=n&bh=n&bc=n&left=n&right=n&ordered=n&
pool=C&ext=COM|NET|ORG|INFO|BIZ|US&exactfirst=y&page=1

Request Object sent back from NI (example):

<REQUEST>
  <Q>domain</Q>
  <ROWS>20</ROWS>
  <BN>n</BN>
  <BH>n</BH>
  <BC>n</BC>
  <F7>n</F7>
  <LEFT>n</LEFT>
  <RIGHT>n</RIGHT>
  <ORDERED>y</ORDERED>
  <POOL>C</POOL>
  <PAGE>1</PAGE>
  <EXACTFIRST>y</EXACTFIRST>
</REQUEST>

Response Object sent back from NI (example):

<RESPONSE>
  <ERRLEV>nowarnings</ERRLEV>
  <OPTIONS>4</OPTIONS>
  <TIME>20030117134547-149</TIME>
  <EXTN>COM|NET|ORG|INFO|BIZ|US</EXTN>
  <DID_YOU_MEAN>apple pie</DID_YOU_MEAN>
  <PAGE_CURRENT>1</PAGE_CURRENT>
  <PAGE_MIN>1</PAGE_MIN>
  <PAGE_MAX>2</PAGE_MAX>
  <PAGE_EXTREME>2</PAGE_EXTREME>
  <RECORDS_RETURNED>100</RECORDS_RETURNED>
  <RECORD_MIN>1</RECORD_MIN>
  <RECORD_MAX>100</RECORD_MAX>
  <RECORD_EXTREME>108</RECORD_EXTREME>
  <QUERYTIME>0.001018</QUERYTIME>
  <D>
   <ID>1</ID>
   <N>applepie</N>
   <S>wqqqqq</S>
  </D>
  <D>
   <ID>2</ID>
   <N>appletreepie</N>
   <S>wqqqqq</S>
  </D>
  .....
  <D>
   <ID>100</ID>
   <N>applescottpie</N>
   <S>wqqqqq</S>
  </D>
</RESPONSE>

3) bulk_check

Parameters expected:

q
ext
XML Objects returned by NI:

extn
records_returned
d
id
n
s
Query (example):
/api.xml?application=bulk_check&version=2&partner=nameintel&
key=12345-12345-12345-12345-12345&customer_ip=100.200.155.230&
q=domain1.com|domain2.com|domain3.com&ext=com|net|info

Request Object will be emtpy so it will not be sent back:

Response Object sent back from NI (example):

<RESPONSE>
  <EXTN>COM|NET|ORG|INFO|BIZ|US</EXTN>
  <RECORDS_RETURNED>100</RECORDS_RETURNED>
  <D>
   <ID>1</ID>
   <N>applepie</N>
   <S>wqqqqq</S>
  </D>
</RESPONSE>

4) areacode_location

Need to know the area code of a location, well this engine is always update to date with new area code information. Instead of downloading a database off the Internet that is inaccurate or out dated, intergrate with our API.

Parameters expected:

code (area code)

XML Objects returned by NI:

areacode
statecode
statelong
gmt

Query (example):

/api.xml?application=areacode_location&version=2&partner=nameintel&
key=12345-12345-12345-12345-12345&customer_ip=100.200.155.230&
code=206

5) ip_location

One of the most used applications we have, knowing where your visitors are coming useful for advertising, fraud protection, and a number of different things.

Parameters expected:

ip (ip address)

XML Objects returned by NI:

ip
country
city
region
isp
img

Query (example):

/api.xml?application=ip_location&version=2&partner=nameintel&
key=12345-12345-12345-12345-12345&customer_ip=100.200.155.230&
ip=206.12.14.208

5. Request and Response Objects

Variable Default Allowed Description
Q ([!] or [^]){0,1} [a-z0-9]{2-65} [$]{0,1} Query String
Query String will accept multiple words. Words must be 2 characters long. Words must be separated by space. Please note that when passing variables to the API they must be URL encoded because they are part of a HTTP GET request. Please note the original query will be cleaned and returned. Queries are case insensitive.

Examples Query Stings: '^micro soft$' – Locates all domains starting with 'Micro' and ending in 'Soft'. '^cat$' – This will only return one domain has it is anchored on both sides. 'cat dog !mouse' – Finds all 'cat' & 'dog' domains excluding domains with 'mouse'
ERRORS 401 - Query String is empty

Variable Default Allowed Description
ROWS 20 [20-100] Rows returned
If any other value below or above the given range is used then 20 will be defaulted.
ERRORS 201 – Row was out of bounds auto-corrected to 20 rows.

Variable Default Allowed Description
BH n n || y || A || B || C Block Hyphens
This will exclude domains with hyphens or allow them. The default is to allow them. The value 'n' and 'A' are the same. The value 'y' and 'B' are the same. The values 'y' and 'n' are deprecated.
ERRORS 202 – BH value not in range or is null, default of “n” will be used.

Variable Default Allowed Description
BN n n || y Block Numbers
This will exclude domains with numbers or allow them. The default is to allow them.
ERRORS 203 – BN value not in range or is null, default of “n” will be used.

Variable Default Allowed Description
BC n n || y || [2-65] Block Characters
This will exclude domains with based on length. 'n' will not exclude any domains. 'y' will exclude domains over 25 characters. And the more advanced feature of giving this parameter any integer between [2-65] will block the corresponding length above that.
ERRORS 204 – BC value not in range or is null, default of “n” will be used.

Variable Default Allowed Description
MORE n '' || 80 more Name Spinner Results
This will allow a user to get more than 20 Name Spinner results
ERRORS

Variable Default Allowed Description
LEFT n n || y Left Anchor
The left most word will be left anchored if left=y. LEFT will also return marked 'y' if the LEFT anchor character is successful parsed in the query string '^'.
ERRORS 205 – LEFT value not in range or is null, default of “n” will be used.

Variable Default Allowed Description
RIGHT n n || y Right Anchor
The left most word will be left anchored if right=y. LEFT will also return marked 'y' if the RIGHT anchor character is successful parsed in the query string '$'.
ERRORS 206 – RIGHT value not in range or is null, default of 'n' will be used.

Variable Default Allowed Description
ORDERED n n || y Ordered words
If the search is ordered then the words contained in the domains returned will be returned in the same order that the words appear in the query string.
ERRORS 207 – ORDERED value not in range or is null, default of “n” will be used.

Variable Default Allowed Description
POOL C A || B || C Pool to Search
The Pool search will only search domains that in a give pool. Pool B is all deleted domains. If the domain is no longer in the zonefile then it is said to be in this pool. Pool A is all domains currently in the zonefile. Pool C, is All domains. It doesn’t matter which pool is given because all pools are searched with the C option is used.

C=all || B=deleted || A=active
ERRORS 208 – POOL value not in range or is null, default of 'C' will be used.

Variable Default Allowed Description
PAGE 1 [0-9]+ Page number
Page must be a value between 1 and the 3000 and cannot exceed the value of PAGE_EXTREME.
ERRORS 210 – PAGE value not in range or is null, default of '1' will be used.

Variable Default Allowed Description
EXACTFIRST n y || n Exact First
There will be a <E></E> element populated in the results which will exactly match what was search for if this variable is set to 'y'.
ERRORS 211 – EXACTFIRST value not in range or is null, default of 'n' will be used.

Variable Default Allowed Description
UNIVERSE [[Number of domains]] NULL || [1-20] How many domains
If for some reason a full set of domain suggestions is not returned then the universe variable will be returned indicating how small the universe of domains is that currently use that word. Most often the universe is zero, because the string is garbage.
ERRORS

Variable Default Allowed Description
INTELLISEARCH n y || n Smart Search
The Intellisearch performs a smart search for the user. We narrow down results based on different criteria.
ERRORS 212 – INTELLISEARCH value not in range or is null, default of 'n' will be used.

Variable Default Allowed Description
F7 n y || n Spell Check
Spell check is a function that will take <Q> and run it against spell check BEFORE searching. We consider this function beta, and we advise it not be used in production areas. We are seeking feedback on this feature. To activate it you will have to explicitly set the value to 'y' as the default is 'n'.
ERRORS

Variable Expect Returned Description
DID_YOU_MEAN [[Spell Checked Query]] Spell Check’s Thoughts
This object will always return with an improved guess at the spelling, it will be NULL if it thinks the spelling passed all checks. You are free to ignore this object or use it in refining the search. This function is like <F7> except it will not do anything to your active query. It is only insight into what it wants to do.

Variable Default Allowed Description
ERRLEV nowarnings warnings || nowarnings Warning Level
If this is set to nowarnings, only 400 level and above error messages will be returned. “warnings” will return all messages, both warnings and errors. By default this is set to the nowarning. To see warnings we advice setting this variable.
ERRORS

Variable Expect Returned Description
TIME ([0-9]+)-([0-9]+) Options
This value is the index back into the session of the current search. Save this variable if the user would like more pages from this same search. Remember to always pass all required variables as well so that if the session is already destroyed another one can be created. If a valid TIME session is passed back most request variables will be ignored. The only variables not ignored are display variables such as rows and page.

Variable Expect Returned Description
EXT COM|NET|ORG|INFO|BIZ|US Extensions
Populated the EXT variable with all extensions that should be returned in the results. Placed extentions in the same order you want to see results returned back in the compressed objects. When we add new extensions we will alert you, all that will be required to see that extension is to list the new TLD in the query. Extensions that get accepted will be placed in the <EXTN> variable

Variable Expect Returned Description
EXTN COM|NET|ORG|INFO|BIZ|US|GOV|EDU Extensions
Returns extensions that got accepted in the <EXT> variable. Use this variable to determine what order the compressed objects return in, such as <S>. Typical searches would be 'COM|NET|ORG|INFO|BIZ|US'.

Errors 209 – EXTN value not in range or is null, default of “COM|NET|ORG|INFO|BIZ|US” will be used.

Variable Expect Returned Description
PAGE_CURRENT [0-9]+ Current Page Number
Displays the current page number

Variable Expect Returned Description
PAGE_MIN 0 || 1 Minimum Page Number
Displays the lowest page number. Variable will be zero when no results are found or one when multiple pages have been found.

Variable Expect Returned Description
PAGE_MAX [0-9]+ Maximum Page Number
Displays the highest page number possible.

Variable Expect Returned Description
PAGE_EXTREME [0-9]+ Highest Page Possible
If more then 3000 results were allowed then in theory this page would be accessible. Keep in mind at all times that no more then 3000 results can be retrieved. This is an arbitrary restriction Name Intelligence set so that people would refine their searches and also restrict data mining.

Variable Expect Returned Description
RECORDS_RETURNED [0-9]+ Records in the display
The number of rows will match the records in the display unless it is the last page. You can expect this many results.

Variable Expect Returned Description
RECORDS_MIN [0-9]+ Start Number
The starting number of the current display. If the results were on the third page and each page was 20 rows long the RECORDS_MIN would be 41.

Variable Expect Returned Description
RECORDS_MAX [0-9]+ Ending Number
The ending number of the current display. If the results were on the third page and each page was 20 rows long the RECORDS_MAX would be 60.

Variable Expect Returned Description
RECORDS_EXTREME [0-9]+ Highest Possible Record Number
The total number of records that exist. Please note it is not possible to reach records over 3000. We ask that users refine their search terms if they ask pages that would produce results over a record id of 3000.

Variable Expect Returned Description
QUERYTIME [[float]] Speed of Search Engine
Private speed variable that do not need to be displayed publicly.

Variable Expect Returned Description
D {xml object} Domain Envelope
For each search result there will be one Domain Envelope. Inside each domain envelope there will be <N>, <ID>, <S> objects.

Please note, we always return a result 0 on the first page of results. This is an exact match for the query, you are free to ignore this result. Your logic should be adapted for the 0 record. Since <RECORDS_RETURNED> may say 20 but it is really 21 including the 0. We start all counts at 1.

Variable Expect Returned Description
ID [0-9]+ Domain Envelope ID
For each search result on every page there will be a unique id for per set of unique criteria.

Variable Expect Returned Description
N {name} second level
The name part of the domain in this envelope.

Variable Expect Returned Description
S p || w || x || h || d || q || e || g Current Status (compressed)
p = registered (parked)
w = registered (has website)
x = registered (no website/has dns)
h = registered (on-hold, generic)
d = available (deleted, had previous owner)
q = available (never registered)
e = registered (on-hold, five day pendingdelete)
g = registered (on-hold, 30 day graceperiod)

Compressed Objects
The <S> object is compressed form of the extension object (<EXTN>) but with status codes instead of domain extensions. For example if the extension object is set to <EXTN>COM|NET|ORG|INFO|BIZ|US</EXTN> then this object would be set to <S>qqwqqq</S>, this would mean that the third spot is ORG and has the code 'w'.

As we add new TLDs in the future, we will announce them, at that point all that it will take to activate them into your application is simply appending the new TLD code to the <EXT> variable. The <EXTN> object will then reflex the new extension along with the <S> object.

6. Errors Node
The Errors node only appears when there is an error or warning message. Each error message is classified into different levels of severity depending on the status. But unlike other protocols like HTTP the WhoisAPI protocol can produce multiple error conditions like a compiler. We suggest that the developer deals with the errors from a descending level of complexity. 500 and 400 level errors will be the worst since they will halt execution of the search engine. 200 level errors are warnings about variables being left null or out of bounds values given. This 200 level warnings are all auto-corrected. 100 level messages have nothing to do with input and processing errors or warnings they deal with the user not receiving any results. 100 level warning are very nice since it means the user has most likely found a domain that is available.

The Error node is set to only show if the level is 400 or above. To turn warning messages on append "&errlev=warnings" to your query string.

Variable Default Allowed Description
ERRLEV nowarnings warnings || nowarnings Warning Level
If this is set to nowarnings, only 400 level and above error messages will be returned. “warnings” will return all messages, both warnings and errors. By default this is set to the nowarning. To see warnings we advice setting this variable.
ERRORS

Error levels

100 level Query succeed – But no results matched

200 level Warning Messages – Not Fatal

400 level Fatal Error – Execution Halted

500 level Name Intelligence - Account Problem or Authentication Issue

© Copyright 2008 Name Intelligence, Inc.

Variable	Default	Allowed	Description
APPNAME		{Application Requested}	Application Title
	Setting the Application handler is the most important step.
ERRORS	501 – Application APPNAME not named or not found.

Variable	Expect Returned	Description
DID_YOU_MEAN	[[Spell Checked Query]]	Spell Check’s Thoughts
	This object will always return with an improved guess at the spelling, it will be NULL if it thinks the spelling passed all checks. You are free to ignore this object or use it in refining the search. This function is like <F7> except it will not do anything to your active query. It is only insight into what it wants to do.

Error levels
100 level	Query succeed – But no results matched
200 level	Warning Messages – Not Fatal
400 level	Fatal Error – Execution Halted
500 level	Name Intelligence - Account Problem or Authentication Issue