V2 API (Preview)

Domainr API (v2 preview)

Notes

• The version 2 API is currently under development, and may change at any time.
• Try it for free at Mashape, using query parameter auth to authenticate.
  • example query: https://domainr.p.mashape.com/v2/search?mashape-key={your-Mashape-API-key}&query=acme%20cafe
• All requests from high-volume commercial developers must include a valid client_id parameter (your API key).
• Requests must come from a whitelisted CORS origin. Please let us know which hostnames you’d like supported. Note: www.domain.com and domain.com are considered separate origins. You do not need to specify localhost or 127.0.0.1. For mobile apps, we will whitelist your API key with *.
• Please get in touch with any questions or comments: [email protected]

General

• the base URL for requests is: https://api.domainr.com/v2
• The API server will respond identically on port 80 (http) and port 443 (https).
• All API commands require a client_id parameter (your API key).

Requests

API arguments should be URL-encoded UTF-8 strings in the querystring of the request URL.

Responses

Responses are in JSON format (application/json). On success or failure, the server will respond with an appropriate HTTP response code (2xx, 4xx, 5xx). In the event of an error, the response will include "message" key describing the error.

{
  "message": "Too legit to quit."
}

Cross-Domain and JSONP

The version 2 API fully supports the CORS (Cross-Origin Resource Sharing) standard for cross-domain API access from the browser. API clients must whitelist their origin hosts (example.com www.example.com staging.example.com) prior to accessing the API. Note: localhost (and equivalent IP addresses) are automatically whitelisted.

JSONP

To query the Domainr API from a browser that does not support CORS, you can request a JSONP response by including the callback parameter with the name of a JavaScript function to call in any API URL. Note: all JSON requests will respond with a 200 OK status to ensure the browser evaluates the response.

API Commands

Search

The search command performs a real-time query of the search term(s) against the known zone database, making recommendations, stemming, Unicode folding, IDN normalization, and other refinements. It accepts the following arguments:

• query (required) — term(s) to search against.
• location — optionally override the IP location detection for country-code TLDs.
• registrar — the domain name of a specific registrar to filter results by that registrar’s supported list of extensions.
• defaults — optionally include a list of comma-separated domain extensions, to include by default.

Example

Request

curl "https://api.domainr.com/v2/search?client_id={client_id}&query=acecafe"

Response

{
  "results": [
    {
      "domain": "ace.coffee",
      "host": "",
      "subdomain": "ace.",
      "zone": "coffee",
      "path": "",
      "registerURL": "https://api.domainr.com/v1/register?domain=ace.coffee&registrar=&source=api"
    },
    {
      "domain": "ace.bar",
      "host": "",
      "subdomain": "ace.",
      "zone": "bar",
      "path": "",
      "registerURL": "https://api.domainr.com/v1/register?domain=ace.bar&registrar=&source=api"
    },
    {
      "domain": "ace.eat",
      "host": "",
      "subdomain": "ace.",
      "zone": "eat",
      "path": "",
      "registerURL": "https://api.domainr.com/v1/register?domain=ace.eat&registrar=&source=api"
    }
  ]
}

Status

The status command checks the availabilty status of one or more domain names. It accepts a single argument domain as a comma-delimited list of domain names.

The response will contain a JSON array of status objects with three keys: domain, status, and summary. The status key is a space-delimited list of status types for the given domain, in increasing order of precedence. The summary key will always contain the last value in the status key.

Example

Request

curl "https://api.domainr.com/v2/status?client_id={client_id}&domain=ace.coffee,acecafe.com,acecafe.net,acecafe.co,acecafe.io"

Response

{
  "status": [
    {
      "domain": "ace.coffee",
      "status": "active",
      "summary": "active"
    },
    {
      "domain": "acecafe.net",
      "status": "active",
      "summary": "active"
    },
    {
      "domain": "acecafe.com",
      "status": "active",
      "summary": "active"
    },
    {
      "domain": "acecafe.co",
      "status": "active",
      "summary": "active"
    },
    {
      "domain": "acecafe.io",
      "status": "undelegated inactive",
      "summary": "inactive"
    }
  ]
}

Domain Status

Domainr returns status as a space-separated list of status flags, in increasing order of priority. The last (right-most) status can be considered the overall or summary status.

Status	Example	Description
unknown		unknown status, usually resulting from an error or misconfiguration
undelegated	hello.edu	the domain is not present in DNS
inactive	nonexistent.xyz	inactive (available for new registration)
pending	morning.cafe	TLD not yet in the root zone file
unregistrable	hello.google	no registrars offer this domain for sale
disallowed	re.coffee	disallowed by the registry, ICANN, or other (wrong script, etc.)
claimed	brand.co	claimed or reserved by some party (not available for new registration)
reserved	google.bargains	explicitly reserved by ICANN, the registry, or another party
dpml	google.bargains	Domains Protected Marks List, reserved for trademark holders
invalid	(a domain with > 64 chars)	technically invalid, e.g. too long or too short
active	ace.coffee	active (registered)
parked	01.net	active and parked
marketed	la.co	explicitly marketed as for sale
premium	ace.pizza	premium domain name for sale by the registry
suffix	blogspot.com	a public suffix according to publicsuffix.org
registrar	dnsimple.com	a domain controlled by a registrar
zone	co.uk	a zone (domain extension) in the Domainr database
tld	com	top-level domain

The status for .com is claimed active suffix zone tld, meaning it is claimed, in active use (registered), a known public suffix, a zone in Domainr’s database, and a TLD. Its status can be summarized as tld.