Document of dotDB API v1.0

dotDB API allows you to search all domain names via API calls programmatically. To get access of dotDB API, you need to subscribe to Expert plan. If you need any help for using dotDB API, like you need a code sample of for accessing dotDB API in your favorite programming language, like Python, Ruby, PHP or etc, please feel free to contact us at [email protected] , we are happy to help :)

Authentication

All dotDB API endpoints need to be accessed with a valid API key. To get your API access key, please visit API Access page, press the Reveal button then you will see your API key. API key should be provided in HTTP Authorization header with Token as the type. Like this

Authorization: Token <Your API key>

with tools like cURL, for example, say you want to get the result of searching keyword apple, then you can write

curl -H "Authorization: Token <Your API key>" https://api.dotdb.com/v1/search?keyword=apple

For Python with requests library, you can write

import requests
resp = requests.get(
    'https://api.dotdb.com/v1/search',
    params={'keyword': 'apple'},
    headers={'Authorization': 'Token <Your API key>'}
)

Search - GET /v1/search

dotDB search result can be retrieved as JSON payload via sending HTTP GET request to endpoint

https://api.dotdb.com/v1/search

Parameters

Parameters can be passed in as URL parameter like this as part of the URL query string

keyword=banana&position=end

Available parameters are

Key Required Description
keyword YES The keyword to search, just like the text you will input in the dotDB search text field. Can be separated by spaces for multiple keyword
position NO The position of keyword is allowed appear, can be beginning, end or any. The default value is any
site_status NO Filter domain based on site status, can be active, parking or inactive. This parameter can repeat multiple times to include different extensions, like site_status=active&site_status=parking .
exclude_alphabets NO Exclude alphabets from search result, can be true, false, 1 or 0. The default value is false
exclude_digits NO Exclude digits from search result, can be true, false, 1 or 0. The default value is false
exclude_hyphens NO Exclude hyphens from search result, can be true, false, 1 or 0. The default value is false
exclude_idns NO Exclude idns from search result, can be true, false, 1 or 0. The default value is false
include_suffix NO Limit the search result to only include given extensions, for example, .com. This parameter can repeat multiple times to include different extensions, like include_suffix=.com&include_suffix=.net. Cannot be used with exclude_suffix in the same time
exclude_suffix NO Exclude the search result to not to include given extensions, for example, .com. This parameter can repeat multiple times to exclude different extensions, like exclude_suffix=.com&exclude_suffix=.net. Cannot be used with include_suffix in the same time
count_sorting NO Sort results in matches by the number of extensions, can be true, false, 1 or 0. The default value is false
page NO The number of result page to return, can be from 1 to 100. The default value is 1

Response

Response will be returned in JSON format. Here's the format

Key Description
items_per_page Number of items to be returned in a page
total_name Number of matched keywords
total_suffix Number of matched extensions
exact_match_total_suffix Number of exact matched extensions
estimate_total When search a keyword and matching too many, to return the result quickly, we estimate the matched keywords and extensions instead of calculate the accurate number. When it is true, it means the total_name and total_suffix are estimate numbers, otherwise it means they are accurate number
parameters The parameters you passed in and used for search
matches The search result matches, it will be an array of object with name key for the matching keyword and suffixes key for an array of matching extensions, count for the number of extensions and site_status contains status of the domain website. It could be empty if nothing matches or page exceeds the last page

Sample response for search weddingshoes

{
  "parameters": {
    "keywords": [
      "weddingshoes"
    ],
    "position": "any",
    "site_status": null,
    "count_sorting": false,
    "page": 1,
    "exclude_alphabets": false,
    "exclude_digits": false,
    "exclude_hyphens": false,
    "exclude_idns": false
  },
  "items_per_page": 30,
  "estimate_total": false,
  "exact_match_total_suffix": 35,
  "total_name": 113,
  "total_suffix": 166,
  "matches": [
    {
      "name": "weddingshoes",
      "count": 35,
      "suffixes": [
        ".com",
        ".tk",
        ".de",
        ".net",
        ".org",
        ".co.uk",
        ".nl",
        ".eu",
        ".xyz",
        ".it",
        ".ca",
        ".ch",
        ".co",
        ".com.br",
        ".com.au",
        ".online",
        ".us",
        ".pl",
        ".in",
        ".top",
        ".uk",
        ".co.za",
        ".shop",
        ".work",
        ".ro",
        ".tv",
        ".gr",
        ".com.ua",
        ".ie",
        ".com.pl",
        ".net.au",
        ".com.my",
        ".gq",
        ".gallery",
        ".direct"
      ],
      "site_status": {
        "active_suffixes": [
          ".com",
          ".nl",
          ".ca",
          ".ch",
          ".com.br",
          ".us",
          ".pl",
          ".co.za",
          ".shop",
          ".work",
          ".ro",
          ".gr",
          ".com.ua",
          ".ie",
          ".com.pl",
          ".com.my",
          ".gq"
        ],
        "active_count": 17,
        "parking_suffixes": [
          ".de",
          ".net",
          ".xyz",
          ".co",
          ".com.au",
          ".online",
          ".top",
          ".uk",
          ".gallery"
        ],
        "parking_count": 9,
        "inactive_suffixes": [
          ".tk",
          ".org",
          ".co.uk",
          ".eu",
          ".it",
          ".in",
          ".tv",
          ".net.au",
          ".direct"
        ],
        "inactive_count": 9
      }
    },
    {
      "name": "1001weddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".com"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "99weddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [
          ".com"
        ],
        "parking_count": 1,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "anellaweddingshoes",
      "count": 1,
      "suffixes": [
        ".co.za"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".co.za"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "bargainweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "belliniweddingshoes",
      "count": 2,
      "suffixes": [
        ".com",
        ".it"
      ],
      "site_status": {
        "active_suffixes": [
          ".com",
          ".it"
        ],
        "active_count": 2,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "bestweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [
          ".com"
        ],
        "parking_count": 1,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "blueweddingshoesinstore",
      "count": 1,
      "suffixes": [
        ".tk"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".tk"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "bridal-weddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "bridalweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "brideweddingshoes",
      "count": 1,
      "suffixes": [
        ".tk"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".tk"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "brisbaneweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [
          ".com"
        ],
        "parking_count": 1,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "buyweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [
          ".com"
        ],
        "parking_count": 1,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "cheapestcheepweddingshoesdiscount",
      "count": 1,
      "suffixes": [
        ".tk"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".tk"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "cheapweddingshoes",
      "count": 2,
      "suffixes": [
        ".com",
        ".biz"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".biz"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "christianlouboutinweddingshoes",
      "count": 1,
      "suffixes": [
        ".tk"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".tk"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "christianltinweddingshoes2010",
      "count": 1,
      "suffixes": [
        ".tk"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".tk"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "comfyweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "custommadeweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "dancingweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".com"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "designerweddingshoes",
      "count": 2,
      "suffixes": [
        ".com",
        ".net"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [
          ".com"
        ],
        "parking_count": 1,
        "inactive_suffixes": [
          ".net"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "designerweddingshoesonline",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [
          ".com"
        ],
        "parking_count": 1,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "discountweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".com"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "dyableweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "dyeableweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "e-weddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "eweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "exclusiveweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [
          ".com"
        ],
        "active_count": 1,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [],
        "inactive_count": 0
      }
    },
    {
      "name": "findyourweddingshoes",
      "count": 1,
      "suffixes": [
        ".com"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".com"
        ],
        "inactive_count": 1
      }
    },
    {
      "name": "flatweddingshoes",
      "count": 2,
      "suffixes": [
        ".com",
        ".tk"
      ],
      "site_status": {
        "active_suffixes": [],
        "active_count": 0,
        "parking_suffixes": [],
        "parking_count": 0,
        "inactive_suffixes": [
          ".com",
          ".tk"
        ],
        "inactive_count": 2
      }
    }
  ]
}

Examples

Search weddingshoes

cURL:

curl -H "Authorization: Token <Your API key>" "https://api.dotdb.com/v1/search?keyword=weddingshoes"

Python:

import requests
resp = requests.get(
    'https://api.dotdb.com/v1/search',
    params={'keyword': 'weddingshoes'},
    headers={'Authorization': 'Token <Your API key>'}
)

Search multiple keyword wedding and shoes

cURL:

curl -H "Authorization: Token <Your API key>" https://api.dotdb.com/v1/search?keyword=wedding+shoes

Python:

import requests
resp = requests.get(
    'https://api.dotdb.com/v1/search',
    params={'keyword': 'wedding shoes'},
    headers={'Authorization': 'Token <Your API key>'}
)

Search ending with apple

cURL:

curl -H "Authorization: Token <Your API key>" https://api.dotdb.com/v1/search?keyword=apple&position=end

Python:

import requests
resp = requests.get(
    'https://api.dotdb.com/v1/search',
    params={
        'keyword': 'apple',
        'position': 'end'
    },
    headers={'Authorization': 'Token <Your API key>'}
)

Search ending with apple, filter out digits and hyphens, only include .com and .net suffix

cURL:

curl -H "Authorization: Token <Your API key>" https://api.dotdb.com/v1/search?keyword=apple&position=end&exclude_digits=true&exclude_hyphens=true&include_suffix=.com&include_suffix=.net

Python:

import requests
resp = requests.get(
    'https://api.dotdb.com/v1/search',
    params={
        'keyword': 'apple',
        'position': 'end',
        'exclude_digits': 'true',
        'exclude_hyphens': 'true',
        'include_suffix': ['.com', '.net']
    },
    headers={'Authorization': 'Token <Your API key>'}
)