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
• Base URL
• HTTP methods
• Input
  • Data model
  • Formats
• Output
  • Data model
    • Overview
    • QueryResult
    • Accounting
    • Error codes
  • Formats

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.

HTTP methods

GET or POST

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.испытание or example.xn--80akhbyknj4f

Domains will be assumed to be fully-qualified and do not have to end with a ., though they may. Examples: example.com or example.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 for example.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 or 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.

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 set max-age to 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.

• 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 ErrorCodes within 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 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 QueryResults 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 and No values, 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.

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 and FooterText 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 or max-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 or password 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)