WHO-API: Domain Name (WHOIS) Lookup

Apr 10, 2018 at 10:07 Twitter · Facebook

Generic internet domain name WHOIS lookup API

The WHOIS API (WHO-API) is a web-based API that allows you to directly query and retrieve information about any registered internet domain name and its associated entities such as registrant, sponsoring registrar, and administrative and technical contacts from its primary registry database. The API presents a programmable interface to the underlying WHOIS system—a collection of protocols, services, and data types that together constitute a query-and-response framework by means of which one is able to obtain information about the assignees of internet resources such as domain names, IP address blocks, and autonomous system numbers. Although WHOIS itself permits querying many sorts of internet resources, WHO-API is restricted to work with only internet domain names, albeit, all generic ones.

WHO-API makes available information such as domain name creation and expiration dates, associated nameservers (as recorded in the registry database), and identifying information such as name, address, phone number, and email address of the registered holder of any given domain name. Such information can often be crucially helpful when researching, detecting, and/or investigating spam, fraud, system intrusion, or other suspicious online activities. Other common usage is checking the availability or current status of a domain name, and obtaining the real-world identity, business location, and contact information of an online business or organization that operates a domain name on the Internet. Several clinical measures have been taken to ensure timely, unrestricted, and free public access to accurate and complete WHOIS information directly from the registry database.

The endpoint for WHO-API is https://dev.kwayisi.org/apis/whois. All API paths presented herein are relative to this base URL. You may append a prettify query string parameter to the complete resource URL to return a human-readable formatted response. Below are the various API resources that are currently available:

• GET /{domain-name}
• GET /{domain-name}/contacts
• GET /{domain-name}/rawtext
• GET /{domain-name}/registrant
• GET /{domain-name}/registrar

GET /{domain-name}

This API resource returns a domain object representing the complete base information about the specified domain name. If the specified domain name is not registered or no WHOIS information could be found for it, an HTTP 404 status response is returned.

Example request

https://dev.kwayisi.org/apis/whois/google.com

Example response

{
    "crdate": "1997-09-15T07:00:00+00:00",
    "cxdate": "2020-09-14T04:00:00+00:00",
    "dnssec": "unsigned",
    "exdate": "2020-09-14T04:00:00+00:00",
    "id": "2138514_DOMAIN_COM-VRSN",
    "name": "google.com",
    "nservs": [
        "ns2.google.com",
        "ns4.google.com",
        "ns3.google.com",
        "ns1.google.com"
    ],
    "status": [
        "clientUpdateProhibited",
        "clientTransferProhibited",
        "clientDeleteProhibited",
        "serverUpdateProhibited",
        "serverTransferProhibited",
        "serverDeleteProhibited"
    ],
    "update": "2018-02-21T18:45:07+00:00"
}

GET /{domain-name}/contacts

This API resource returns an array of three contact objects representing, sequentially, the administrative, technical, and billing contacts of the specified domain name. If any of the contact types is not found, null is placed in its stead. If you want to pull a specific contact without fetching the others, you could do so by appending /admin, /tech, or /billing to the resource path for the administrative, technical, or billing contact respectively. E.g., [BASE]/google.com/contacts/admin. If no WHOIS data exists for the given domain name, an HTTP 404 status response is returned.

Example request

https://dev.kwayisi.org/apis/whois/google.com/contacts

Example response

[
    {
        "id": null,
        "address": {
            "city": "Mountain View",
            "country": "US",
            "region": "CA",
            "street": "1600 Amphitheatre Parkway,",
            "zip": "94043"
        },
        "email": "dns-admin@google.com",
        "fax": {
            "number": "+1.6502530001",
            "ext": null
        },
        "name": "Domain Administrator",
        "org": "Google LLC",
        "phone": {
            "number": "+1.6502530000",
            "ext": null
        }
    },
    ...
]

GET /{domain-name}/rawtext

This API resource returns a plain text response representing the raw text response as received from the contacted WHOIS server. Notice that unlike the other API resources, this one does not return a JSON response. If no WHOIS data could be found for the specified domain name, an HTTP 404 status response is returned.

Example request

https://dev.kwayisi.org/apis/whois/google.com/rawtext

Example response

% IANA WHOIS server
% for more information on IANA, visit http://www.iana.org
% This query returned 1 object

refer:        whois.verisign-grs.com
domain:       COM

organisation: VeriSign Global Registry Services
address:      12061 Bluemont Way
address:      Reston Virginia 20190
address:      United States
...

GET /{domain-name}/registrant

This API resource returns a contact object representing the details of the registrant of the specified domain name as recorded in the WHOIS registry. If no WHOIS data exists for the given domain name, an HTTP 404 status response is returned.

Example request

https://dev.kwayisi.org/apis/whois/google.com/registrant

Example response

{
    "id": null,
    "address": {
        "city": "Mountain View",
        "country": "US",
        "region": "CA",
        "street": "1600 Amphitheatre Parkway,",
        "zip": "94043"
    },
    "email": "dns-admin@google.com",
    "fax": {
        "number": "+1.6502530001",
        "ext": null
    },
    "name": "Domain Administrator",
    "org": "Google LLC",
    "phone": {
        "number": "+1.6502530000",
        "ext": null
    }
}

GET /{domain-name}/registrar

This API resource returns a registrar object representing the details of the administrative registrar of the specified domain name. If no WHOIS data exists for the given domain name, an HTTP 404 status response is returned.

Example request

https://dev.kwayisi.org/apis/whois/google.com/registrar

Example response

{
    "email": "abusecomplaints@markmonitor.com",
    "id": 292,
    "name": "MarkMonitor, Inc.",
    "phone": "+1.2083895740",
    "reseller": null,
    "server": "whois.markmonitor.com",
    "url": "http://www.markmonitor.com"
}

Address object

Contact object

Domain object

Faxphone object

Registrar object