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>'}
)