Document of dotDB API
The dotDB API allows you to search for domain names programmatically through API calls. You can access data on all registered domains quickly and easily with this API, making it an efficient and convenient way to find the information you need. In order to gain access to the dotDB API, you must subscribe to the Expert plan. If you need help using the dotDB API, such as a code sample for accessing it in your preferred programming language, like Python, Ruby, PHP, etc., please don't hesitate to contact us at support@dotdb.com . We are more than happy to help!
Authentication
To access all dotDB API endpoints, you need a valid API key. To obtain yours, go to the API Access page and click the Reveal button, then you will see your API key. The API key should then be included in the HTTP Authorization header with Token as the type, like so:
Authorization: Token <Your API key>
For example, if you want to get the result of searching for the keyword happy using a tool like cURL, you would write:
curl -H "Authorization: Token <Your API key>" https://api.dotdb.com/v2/search?keyword=happy
For Python with requests library, you can write
import requests
resp = requests.get(
'https://api.dotdb.com/v2/search',
params={'keyword': 'happy'},
headers={'Authorization': 'Token <Your API key>'}
)
Search - GET /v2/search
A HTTP GET request sent to the endpoint will return the dotDB search result as a JSON payload.
https://api.dotdb.com/v2/search
Parameters
Parameters can be included in the URL query string as part of the URL, like this:
keyword=happy&position=end
Available parameters are
| Key | Required | Description |
|---|---|---|
| keyword | YES | The keywords to search - similar to the text you would enter in the dotDB search text box - can be separated by spaces for searching multiple keywords. |
| position | NO | The position of the keyword is allowed to be at the beginning, end, or any part of the query string; the default setting is "any". |
| site_status | NO | Filter domain based on site status, can be active, parked or inactive. This parameter can repeat multiple times to include different status types, like site_status=active,parked. |
| keyword_exclude | NO |
Exclude keywords that contain alphabets, digits, hyphens, idns. For example, if you wish to have your search results show only keywords without digits and hyphens, you can add keyword_exclude=digits,hyphens
|
| include_suffix | NO |
Limit the search result to include only given extensions, such as .com. You can add more than one suffix to include different extensions, for example include_suffix=.com,.net. Note that you cannot use this parameter with exclude_suffix at the same time.
|
| exclude_suffix | NO |
Exclude the given extensions from the search result, for example, .com. The value of the parameter can be multiple suffixes to exclude different extensions, such as exclude_suffix=.com,.net. Note that you cannot use this parameter with include_suffix at 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 | If a search query yields too many matches, we estimate the matched keywords and extensions as a way to quickly return results. When it is true, then the values of total_name and total_suffix are estimates; otherwise, they represent an accurate count. |
| parameters | The parameters you passed in and used for search |
| matches |
The search result matches will be an array of objects, each containing a name key for the matching keyword, a suffixes key for an array of matching extensions, a count for the number of extensions, and a site_status which indicates the status of the domain website.It could be empty if no matches are found or the page exceeds the last page.
|
birthdayparty
{
"parameters": {
"keywords": [
"birthdayparty"
],
"position": "any",
"keyword_exclude": null,
"site_status": null,
"count_sorting": false,
"page": 1
},
"items_per_page": 30,
"estimate_total": false,
"exact_match_total_suffix": 58,
"total_name": 941,
"total_suffix": 1193,
"matches": [
{
"name": "birthdayparty",
"count": 58,
"suffixes": [
".com",
".de",
".net",
".org",
".co.uk",
".cn",
".ru",
".nl",
".xyz",
".info",
".fr",
".eu",
".it",
".ca",
".co",
".ch",
".com.au",
".online",
".us",
".in",
".se",
".be",
".shop",
".uk",
".co.za",
".me",
".jp",
".ir",
".io",
".club",
".app",
".ro",
".co.nz",
".tv",
".space",
".co.in",
".pt",
".ie",
".website",
".vn",
".one",
".africa",
".com.my",
".studio",
".agency",
".hk",
".sg",
".com.sg",
".lu",
".la",
".vegas",
".deals",
".rsvp",
".abudhabi",
".gq",
".ga",
".cf",
".ml"
],
"site_status": {
"active_suffixes": [
".de",
".org",
".cn",
".ru",
".nl",
".info",
".fr",
".eu",
".ca",
".co",
".ch",
".online",
".us",
".se",
".be",
".shop",
".uk",
".co.za",
".me",
".jp",
".ir",
".io",
".ro",
".co.nz",
".tv",
".space",
".co.in",
".pt",
".ie",
".website",
".vn",
".one",
".africa",
".com.my",
".studio",
".agency",
".hk",
".sg",
".com.sg",
".lu",
".la",
".vegas",
".rsvp",
".abudhabi"
],
"active_count": 44,
"parked_suffixes": [
".com",
".net",
".co.uk",
".xyz",
".it",
".in",
".club",
".app",
".deals"
],
"parked_count": 9,
"inactive_suffixes": [
".com.au",
".gq",
".ga",
".cf",
".ml"
],
"inactive_count": 5
}
},
{
"name": "101kidsbirthdaypartytips",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "10thbirthdayparty",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "10yearoldboybirthdaypartyideas",
"count": 1,
"suffixes": [
".ga"
],
"site_status": {
"active_suffixes": [
".ga"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "11yearoldboybirthdaypartyideas",
"count": 1,
"suffixes": [
".ga"
],
"site_status": {
"active_suffixes": [
".ga"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "13thbirthdaypartyideas",
"count": 1,
"suffixes": [
".net"
],
"site_status": {
"active_suffixes": [
".net"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "16thbirthdayparty",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "16thbirthdaypartyideas",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [],
"active_count": 0,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "18thand21stbirthdaypartythemes",
"count": 1,
"suffixes": [
".info"
],
"site_status": {
"active_suffixes": [],
"active_count": 0,
"parked_suffixes": [
".info"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "18thbirthdayparty",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "18thbirthdaypartyideas",
"count": 2,
"suffixes": [
".com",
".ga"
],
"site_status": {
"active_suffixes": [
".ga"
],
"active_count": 1,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "1stbirthdayparty",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [],
"active_count": 0,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "1stbirthdaypartyideas",
"count": 2,
"suffixes": [
".com",
".net"
],
"site_status": {
"active_suffixes": [
".net"
],
"active_count": 1,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "1stbirthdaypartypro",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "1stbirthdaypartyspecialist",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "1stbirthdaypartysupplies",
"count": 2,
"suffixes": [
".com",
".org"
],
"site_status": {
"active_suffixes": [
".org"
],
"active_count": 1,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "1stbirthdaypartytheme",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [],
"active_count": 0,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "2020birthdayparty",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "21stbirthdayparty",
"count": 2,
"suffixes": [
".com",
".com.au"
],
"site_status": {
"active_suffixes": [
".com.au"
],
"active_count": 1,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "21stbirthdaypartyideas",
"count": 2,
"suffixes": [
".com",
".net"
],
"site_status": {
"active_suffixes": [
".net"
],
"active_count": 1,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "30thbirthdayparty",
"count": 2,
"suffixes": [
".com",
".com.au"
],
"site_status": {
"active_suffixes": [
".com.au"
],
"active_count": 1,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "30thbirthdaypartyideas",
"count": 1,
"suffixes": [
".org"
],
"site_status": {
"active_suffixes": [
".org"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "40th-birthdaypartyideas",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "40thbirthdayparty",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "40thbirthdaypartyideas",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [],
"active_count": 0,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "50birthdayparty",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "50thbirthdaypartyideas",
"count": 2,
"suffixes": [
".com",
".net"
],
"site_status": {
"active_suffixes": [
".net"
],
"active_count": 1,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "5150birthdayparty",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [],
"active_count": 0,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "60thbirthdaypartyideasgifts",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [
".com"
],
"active_count": 1,
"parked_suffixes": [],
"parked_count": 0,
"inactive_suffixes": [],
"inactive_count": 0
}
},
{
"name": "70thbirthdaypartyideas",
"count": 1,
"suffixes": [
".com"
],
"site_status": {
"active_suffixes": [],
"active_count": 0,
"parked_suffixes": [
".com"
],
"parked_count": 1,
"inactive_suffixes": [],
"inactive_count": 0
}
}
]
}
Examples
Search birthdayparty
cURL:
curl -H "Authorization: Token <Your API key>" "https://api.dotdb.com/v2/search?keyword=birthdayparty"Python:
import requests
resp = requests.get(
'https://api.dotdb.com/v2/search',
params={'keyword': 'birthdayparty'},
headers={'Authorization': 'Token <Your API key>'}
)
Search multiple keyword birthday and party
cURL:
curl -H "Authorization: Token <Your API key>" "https://api.dotdb.com/v2/search?keyword=birthday+party"Python:
import requests
resp = requests.get(
'https://api.dotdb.com/v2/search',
params={'keyword': 'birthday party'},
headers={'Authorization': 'Token <Your API key>'}
)
Search ending with happy
cURL:
curl -H "Authorization: Token <Your API key>" "https://api.dotdb.com/v2/search?keyword=happy&position=end"Python:
import requests
resp = requests.get(
'https://api.dotdb.com/v2/search',
params={
'keyword': 'happy',
'position': 'end',
},
headers={'Authorization': 'Token <Your API key>'}
)
Search ending with happy, filter out digits and hyphens, only include .com and .net suffix
cURL:
curl -H "Authorization: Token <Your API key>" "https://api.dotdb.com/v2/search?keyword=happy&position=end&keyword_exclude=digits,hyphens&include_suffix=.com,.net"Python:
import requests
resp = requests.get(
'https://api.dotdb.com/v2/search',
params={
'keyword': 'happy',
'position': 'end',
'keyword_exclude': 'digits,hyphens',
'include_suffix': '.com,.net'
},
headers={'Authorization': 'Token <Your API key>'}
)
Bulk Search API is only available in the Enterprise Plan, please contact us if you would like to use it.
Bulk Search - POST /v1/search/bulk
A HTTP POST request sent to the endpoint will return the dotDB search result as a JSON payload.
https://api.dotdb.com/v1/search/bulk
Parameters
Available parameters are
| Key | Required | Type | Default | Description |
|---|---|---|---|---|
| keywords | YES | Array | The keywords to search - similar to the text you would enter in the dotDB search text box - can be separated by spaces for searching multiple keywords. The upper limit of a single request is 10,000 keywords. | |
| position | NO | String | any |
The position of the keyword is allowed to be at the beginning, end, or any part of the query string.
|
| site_status | NO | Array | ['active', 'parked', 'inactive'] |
Filter domain based on site status, can be active, parked or inactive. |
| keyword_exclude | NO | Array | [] |
Exclude keywords that contain alphabets, digits, hyphens, idns.
|
| include_suffix | NO | Array | [] |
Limit the search result to include only given extensions, such as .com. You can add more than one suffix to include different extensions.
|
| note | NO | String | If there is no note value given, the first and last keywords will be used as the note value. |
Response
Response will be returned in JSON format. Here's the format
| Key | Description |
|---|---|
| id | The UUID for each bulk search request. |
| status | The status of the server that has received the request. |
| total_keywords | The total keywords that the server received. |
The response example:
{
"id": "4b33f616-28ad-44dc-859c-c21fce26cec2",
"status": "received",
"total_keywords": 500,
}
When a bulk search request is done, the server will make an HTTP POST call to the Webhook URL you have stored, an example of which is below:
{
"event": "BULK SEARCH",
"type": "COMPLETED",
"content": {
"id": "4b33f616-28ad-44dc-859c-c21fce26cec2",
"total_keywords": "123",
"link": "https://api.dotdb.com/v1/search/bulk/4b33f616-28ad-44dc-859c-c21fce26cec2"
}
}You can use the link above to make a GET request and get the result of the bulk search. Please note that this result will only be kept for 30 days. For more details about the link, please refer to the following API:
Bulk Search - GET /v1/search/bulk/<Your Bulk Search Request UUID>
A HTTP GET request sent to the endpoint will return the dotDB search result as a JSON payload.
https://api.dotdb.com/v1/search/bulk/<Your Bulk Search Request UUID>
Response
Response will be returned in JSON format. Here's the format
| Key | Description |
|---|---|
| id | The UUID for each bulk search request. |
| total_keywords | The total number of keywords processed by this bulk search. |
| status | Current processing status. |
| results | The query results of all keywords in this bulk search. |
The response example:
{
"id": "4b33f616-28ad-44dc-859c-c21fce26cec2",
"total_keywords": "123",
"status": "Done",
"results": [
{
"keyword": "birthday",
"exact_match_total_suffix": "123",
"total_name": "1234",
"total_suffix": "123456",
},
{
"keyword": "party",
"exact_match_total_suffix": "321",
"total_name": "4321",
"total_suffix": "654321",
},
...
]
}