Whois API reference
This page provides technical information about using the Hexillion Whois API. For an overview of features, benefits, and pricing, see the main Whois API page.
Contents
Overview
The Whois API takes a domain name or IP address as input, determines the right Whois server or servers to query, sends queries to those servers via a large pool of IP addresses, parses the results, and returns the results to you in real time in either XML or JSON format.
Base URL
http://hexillion.com/rf/xml/1.0/whois/
or
https://hexillion.com/rf/xml/1.0/whois/
We recommend making this URL configurable in your software instead of hard-coding it.
Whether you use plain HTTP or HTTPS for your queries is up to you. Using a session key from the authentication service will avoid sending your password in the clear, but HTTP will still leave your query activity exposed to eavesdroppers and run the risk of session hijacking. HTTP may offer slightly better performance than HTTPS, however.
NOTE
Though the URL contains the string “xml”, the service can also produce other representations such as JSON. Simply request the format you want using the HTTP Accept
header.
HTTP methods
-
GET
orPOST
-
Sends a real-time Whois query through our system and returns the results.
Example request (using a session key in a cookie):
GET https://hexillion.com/rf/xml/1.0/whois/?query=yahoo.com HTTP/1.1 Host: hexillion.com Accept: application/vnd.hexillion.whois-v2+xml Cookie: HexillionSession=54196e78f6bc9941a46fa1435c1c71a8f8de8d820006b1a9aca9229999267365
Response from the server (truncated):
HTTP/1.1 200 OK Date: Fri, 27 Mar 2015 04:23:18 GMT P3P: CP="NOI ADMi OUR STP UNI" Set-Cookie: HexillionSession=54196e78f6bc9941a46fa1435c1c71a8f8de8d820006b1a9aca9229999267365; path=/; HttpOnly Cache-Control: no-cache Content-Type: application/vnd.hexillion.whois-v2+xml; charset=utf-8 Content-Length: 19783 <?xml version="1.0" encoding="utf-8"?> <ServiceResult xmlns="https://hexillion.com/namespaces/xml/whois/2"> <ErrorCode>Success</ErrorCode> <Message>The service successfully processed your request.</Message> <QueryResult> <QueryString>yahoo.com</QueryString> <ServerName>whois.markmonitor.com</ServerName> <ErrorCode>Success</ErrorCode> <FoundMatch>Yes</FoundMatch>
See the full response body.
Input
Data model
The Whois service accepts the following arguments:
-
query
(required) -
A domain name or IP address string for which to do a query.
A domain name can be an internationalized domain name (IDN) with Unicode characters or ASCII-compatible (Punycode) encoding. Examples:
example.испытание
orexample.xn--80akhbyknj4f
Domains will be assumed to be fully-qualified and do not have to end with a
.
, though they may. Examples:example.com
orexample.com.
The API will determine the longest portion of a domain that has actually been registered and will make back-end Whois queries for just that portion. For example, given
www.example.com
as input, the service will actually issue queries forexample.com
.An IP address can be an IPv4 or IPv6 address textual representation. IPv4 addresses should be in the common dotted-quad form (
192.0.2.1
). IPv6 addresses should conform to the textual representations described in RFC 3513. -
inv
- Providing this with a value of
1
ortrue
will cause the service to “invert” the query. That is, if thequery
value is a domain name, the service will try to look up an IP address for that domain name and do the Whois query for the IP address. Similarly, ifquery
is an IP address, the service will attempt a “reverse DNS” lookup to get a domain name and then do Whois queries for that domain name. The DNS queries (and thus your request to the Whois API) may not succeed. It’s generally best for you to do any such DNS lookups on your end before calling the Whois API, but the “invert” feature can be convenient in some cases. -
max-age
-
Sets the maximum age of the returned records and thus controls the caching behavior of the Whois API.
To improve performance and conserve Whois query resources, our currently system caches Whois records for up to 24 hours. This means that if you request records for
example.com
and then request them again one hour later, you will receive exactly the same records both times. If you’re using the API to watch for updates to a Whois record, for example, the caching may be a problem. In that case, you can setmax-age
to0
to circumvent the caching and ensure an up-to-the-minute response.Several things to note about this feature:
-
Only a value of
0
is currently valid formax-age
. To get the default caching behavior, don’t usemax-age
in your query at all. -
For the time being, as a precaution, there is still a 60-second minimum cache time.
-
Queries with
max-age=0
cost 1.5 service units.
-
-
sessionKey
- Provides the API with your session key obtained from the authentication API if your HTTP client does not manage cookies for you. The sessionKey should be treated as an opaque character string of variable length.
-
username
-
password
- These send your username and password to the API as an alternative to using a session key from the authentication API. It’s generally better to use session keys, but sending username and password in each request is another option. You should use HTTPS for your requests to protect your credentials on the network.
Formats
Use application/x-www-form-urlencoded
in the bodies of POST
requests or the query portion of the URL in GET
requests. (The typical percent-encoded name-value pairs, essentially.) Whether using GET
or POST
, any non-ASCII characters in the input must be encoded as UTF-8 prior to further encoding.
Output
Data model
Overview
Each Whois request is serviced in real time and involves one or more queries to Whois servers on the back end. The response you get from the Whois service will include results from all of these queries, each in a QueryResult
. The results are sent to you in reverse chronological order: the last, most-specific result will appear first in the response. Earlier results are nested within later results.
There’s an outer ServiceResult
, and the ErrorCode
immediately under it pertains to our service. There will be other ErrorCode
s within QueryResult
s that pertain to the back-end Whois queries made by the service.
Responses from the API always include the raw response text of successful Whois queries, even if the system cannot parse that text.
Parsing happens in several stages, so there may be useful parsed data in the result even if part of the parsing fails, yielding a ParseFailed
error. It’s important to actually look for the fields you want in the response rather than simply relying on the value of ErrorCode
.
Parsed fields appear in the response in roughly the same order as they appear in the raw Whois record.
QueryResult
The QueryResult
section of the output documents the results from a single back-end Whois query. It will also contain nested QueryResult
s for any previous Whois queries in the sequence.
-
QueryString
- This member shows what text was actually sent to the back-end server as a query.
-
ServerName
- Gives the domain name of the Whois server queried.
-
ErrorCode
- Tells the outcome of the query and is further explained below.
-
FoundMatch
- Indicates whether the query yielded a Whois record (and not just an error message, for example). This is particularly useful for checking domain name availability. In addition to the possible
Yes
andNo
values,FoundMatch
may also have a value ofReserved
to indicate the special case of a domain’s being unavailable for registration without necessarily having a record with contact information. A value ofUnknown
indicates that the service couldn’t determine whether the query result actually contained a record—often due to lack of parsing support. -
WhoisRecord
-
If the Whois query returned a record, it will be included here in several different ways depending on the success of the parsing.
-
RawText
- The full, raw text of the record returned, regardless of parsing success.
-
StrippedText
- Raw text of the record stripped of notices and instructions from the top and the bottom. Sometimes legal notices take more space than the actual record contents, so having them removed can save valuable display or storage space.
HeaderText
andFooterText
will contain the stripped-off portions.
RawText
=HeaderText
+StrippedText
+FooterText
-
CreatedDate
-
UpdatedDate
-
ExpiresDate
-
DatabaseUpdatedDate
- These are dates pulled from the record, normalized, and presented in Internet Date/Time Format, a profile of ISO 8601 format.
The rest of the contents of
WhoisRecord
are collections of fields parsed from the Whois record. These character strings are included verbatim—exactly as they appear in the record—without any further normalization. Each field can have multiple lines. See the schema for your chosen output type for a full list of possible fields. -
Accounting
The Accounting
section provides a convenient accounting of the cost to service the request, your account balance, and recent usage.
Error codes
Error codes immediately within a ServiceResult
relate to your call to our service, not to back-end queries done by our service. There will be a Message
to briefly explain the error code. Possible values include:
-
Success
- The Whois service successfully processed your request (though it may not have resulted in successful back-end queries).
-
NoQuery
- Your request did not include a value for the
query
parameter. -
InvalidQuery
- The
query
parameter in your request did not include a valid domain name or IP address string. -
InvalidOption
- One of the options in your request (such as
inv
ormax-age
) had an invalid value. -
DnsLookupFailed
- You requested an “inverse” query via the
inv
option, but it couldn’t be completed because a DNS lookup for your query failed. -
RequestLimitReached
- Your account doesn’t have enough service units left to complete the request.
-
RequestsTooFast
- Your request can’t be processed because you have already reached your account’s limit of simultaneous requests (10 by default).
-
AuthenticationFailed
- The
username
orpassword
you supplied wasn’t recognized. -
NotAuthorized
- (This code is not currently used.)
-
NotLicensed
- (This code is not currently used.)
-
InvalidSessionKey
- The session key supplied was malformed (perhaps truncated) or is now invalid due to a software update on the server.
-
SessionExpired
- The session key has expired. Use the authentication API to get a new one.
-
Unexpected
- Something unexpected went wrong on the server.
Error codes within a QueryResult
relate to a back-end Whois query and the processing of its result. Possible values include:
-
Success
- The back-end query and its processing were completely successful.
-
CouldNotResolveServerName
- Our system could not get an IP address for the Whois server’s domain name.
-
NoWhoisServerForDomain
- The domain name you specified does not have a public, port-43 Whois server associated with it as far as we know.
-
NoParsingSupportForServer
- Our service was able to obtain a raw Whois record but doesn’t know how to parse records from the source Whois server.
-
ParseFailed
- Some part of the Whois record parsing process failed. Depending on the point of failure, your results may still have all the parsed fields you need or none at all.
-
Unknown
- Something unexpected went wrong while doing the back-end query or processing its results.
-
ServerTooBusy
- The queried Whois server has indicated that it is too busy to fulfill requests.
-
UserIsBlocked
- A back-end Whois server has blocked a query from our system. This error occurs infrequently, and often the blockage is spurious. Re-trying your request may succeed.
-
ReceiveBufferFull
- The back-end Whois server sent more data than our system was prepared to accept. (You should not see this error in practice—it would likely indicate a malicious or severely-malfunctioning Whois server.)
-
TimedOut
-
AddressNotAvailable
-
NetworkDown
-
NetworkUnreachable
-
ConnectionAborted
-
ConnectionReset
-
ConnectionRefused
-
HostUnreachable
- These are all network errors that would prevent getting a Whois record but are likely temporary.
Formats
All response bodies are encoded in UTF-8, and any Whois record data included have been converted (if necessary) to Unicode from their original character set. End-of-line characters are normalized to CRLF
in keeping with other Internet standards.
Use the HTTP Accept
header in your requests to select one of the following MIME types for the response:
-
application/vnd.hexillion.whois-v2+xml
- Version 2 XML format. (example)
-
application/vnd.hexillion.whois-v2+json
- Version 2 JSON format. (example)
- (any other MIME type)
- The original XML format served as
text/xml
for backward compatibility. (example)