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.
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.
You should use the authentication API first to get a session key before using the Whois API.
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.
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
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
Content-Type: application/vnd.hexillion.whois-v2+xml; charset=utf-8
<?xml version="1.0" encoding="utf-8"?>
<Message>The service successfully processed your request.</Message>
See the full response body.
The Whois service accepts the following arguments:
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:
Domains will be assumed to be fully-qualified and do not have to end with a
., though they may. Examples:
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 for
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.
- Providing this with a value of
true will cause the service to “invert” the query. That is, if the
query 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, if
query 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.
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 set
0 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 for
max-age. To get the default caching behavior, don’t use
max-age in your query at all.
For the time being, as a precaution, there is still a 60-second minimum cache time.
max-age=0 cost 1.5 service units.
- 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.
- 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.
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
POST, any non-ASCII characters in the input must be encoded as UTF-8 prior to further encoding.
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
QueryResults 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
Parsed fields appear in the response in roughly the same order as they appear in the raw Whois record.
QueryResult section of the output documents the results from a single back-end Whois query. It will also contain nested
QueryResults for any previous Whois queries in the sequence.
- This member shows what text was actually sent to the back-end server as a query.
- Gives the domain name of the Whois server queried.
- Tells the outcome of the query and is further explained below.
- 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
FoundMatch may also have a value of
Reserved to indicate the special case of a domain’s being unavailable for registration without necessarily having a record with contact information. A value of
Unknown indicates that the service couldn’t determine whether the query result actually contained a record—often due to lack of parsing support.
If the Whois query returned a record, it will be included here in several different ways depending on the success of the parsing.
- The full, raw text of the record returned, regardless of parsing success.
- 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.
FooterText will contain the stripped-off portions.
- 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 section provides a convenient accounting of the cost to service the request, your account balance, and recent usage.
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:
- The Whois service successfully processed your request (though it may not have resulted in successful back-end queries).
- Your request did not include a value for the
query parameter in your request did not include a valid domain name or IP address string.
- One of the options in your request (such as
max-age) had an invalid value.
- You requested an “inverse” query via the
inv option, but it couldn’t be completed because a DNS lookup for your query failed.
- Your account doesn’t have enough service units left to complete the request.
- Your request can’t be processed because you have already reached your account’s limit of simultaneous requests (10 by default).
password you supplied wasn’t recognized.
- (This code is not currently used.)
- (This code is not currently used.)
- The session key supplied was malformed (perhaps truncated) or is now invalid due to a software update on the server.
- The session key has expired. Use the authentication API to get a new one.
- 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:
- The back-end query and its processing were completely successful.
- Our system could not get an IP address for the Whois server’s domain name.
- The domain name you specified does not have a public, port-43 Whois server associated with it as far as we know.
- Our service was able to obtain a raw Whois record but doesn’t know how to parse records from the source Whois server.
- 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.
- Something unexpected went wrong while doing the back-end query or processing its results.
- The queried Whois server has indicated that it is too busy to fulfill requests.
- 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.
- 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.)
- These are all network errors that would prevent getting a Whois record but are likely temporary.
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:
- Version 2 XML format. (example)
- Version 2 JSON format. (example)
- (any other MIME type)
- The original XML format served as
text/xml for backward compatibility. (example)