Table of Contents

Integrate VERISIGN® DomainScope data into your application with our suite of free APIs. This features domain registry data, daily updated domain drop information and trends from recently registered domain names to help find the best available .com, .net, .tv and .cc domain names

The APIs provide an HTTP interface to the data behind VERISIGN® DomainScope. More information about DomainScope can be found here . All API requests require an API Key and are rate limited.

The VERISIGN® DomainScope API suite offers flexibility with filters that allow you to get the most out of VERISIGN® DomainScope's unique data.

NOTE: Domain Name Lookup API calls for already registered domain names like Verisign.com will NOT return any data except the fact that domain name is unavailable.

Every request requires an API Key.Read the documentation and then create and manage your API key from your profile page.The API Key must be placed in the X-DOMAINSCOPE-APIKEY request header.

Rate limits are tied to an API Key. The default rate limit is 20 requests per min. If you desire a higher limit please contact us after you have created your API key. Every response contains 4 headers that describe the current state of the rate limit:

The VERISIGN® DomainScope API suite includes seven APIs to provide programmatic access to VERISIGN® DomainScope's data. The VERISIGN® DomainScope API suite also has a number of filter options to refine the data. The APIs are listed below
  1. NXD Search
  2. Pending Delete Search
  3. Domain Name Lookup
  4. Top Trending Keywords
  5. Trending Keywords
  6. Top Popular Keywords
  7. Popular Keywords

The list of Non eXistent Domains can be fetched using the NXD Search API. Requests can be made with or without keywords or domain names. Below is the list of request specifications expected by the NXD Search API

Specification
Spec Description
URL /api/v2/domains/nxd
Method < The request type > : GET
URL Parameters No URL parameters exist for the latest version of NXD. All the filters are accessible through Query String Parameters
Query string parameters All the parameters supported via NXD API uses query string parameters
Required None
Optional

 

 

Parameter
Description
Additional Notes
fields Used to limit the response with limited set of fields. Supported fields include one or more of the below: all, domain_name, seven_day_score, thirty_day_score, is_featured, is_available, previously_registered, is_idn, thirty_day_hourly_req, seven_day_unique_req, thirty_day_unique_req, seven_day_total_req, thirty_day_total_req, seven_day_business_hour_req, thirty_day_business_hour_req, geog_breakout

Notes

  • If any of these specific fields are requested, only domain_name + the requested set of fields are shown.
  • If 'fields' is not provided as a request parameter, domain_name, seven_day_score and thirty_day_score are shown by default.

Example: fields = [all] responds with all the fields in the response

Example: fields=geog_breakout responds with domain_name and geog_breakout

domain_name is defaulted in response with all the fields requests

domain_names

List of domain names can be provided to filter the response based on the domain name. One or more domain names can be provided Example: domain_names=fivedollarpoker.comwill return the default set of fields for NXD response related to fivedollarpoker.com
is_featured Filter to show only featured domains calculated by Data Analyzer. Absence of this filter will return all the domains

Example: is_featured=[boolean] i.e [true/false]

true will return featured domains and false will return non featured domains

is_idn Filter to show only IDNs. Absence of filter will return all domains including IDNs and non IDNs. Options are true and false

Example: is_idn=[boolean] i.e [true/false]

true will return IDNs and false will return non IDNs

seven_day_score_min Filter to specify minimum value of seven day score. The valid values are between 0 to 10

Example: seven_day_score_min=7

Response returned will contain seven_day_score greater than 7

seven_day_score_max

Filter to specify maximum value of seven day score. The valid values are between 0 to 10

Example: seven_day_score_max=7

Response returned will contain seven_day_score less than 7

seven_day_score_range

Filter to specify range value of seven day score. The valid values are between 0 to 10

Example: seven_day_score_range=8-10

Response returned will contain seven_day_score between 8 to 10

thirty_day_score_min

Filter to specify minimum value of thirty day score. The valid values are between 0 to 10 Example: thirty_day_score_min=7

Response returned will contain thirty_day_score greater than or equal to 7

thirty_day_score_max Filter to specify maximum value of thiry day score. The valid values are between 0 to 10

Example: thirty_day_score_max=7

Response returned will contain thirty_day_score less than or equal to 7

thirty_day_score_range Filter to specify range value of thirty day score. The valid values are between 0 to 10

Example: thirty_day_score_range=8-10

Response returned will contain thirty_day_score between 8 to 10

seven_day_total_req_min Filter to specify minimum value for seven day total requests. The valid values positive values between 0 to 3000000

Example: seven_day_total_req_min=120

Response returned will contain seven_day_total_req greater than or equal to 120

seven_day_total_req_max Filter to specify maximum value for seven day total requests. The valid values positive values between 0 to 3000000

Example: seven_day_total_req_max=120

Response returned will contain seven_day_total_req less than or equal to 120

seven_day_total_req_range Filter to specify range value for seven day total requests. The valid values positive values between 0 to 3000000

Example: seven_day_total_req_range=120-220

Response returned will contain seven_day_total_req greater than or equal to 120 and less than or equal to 220

thirty_day_total_req_min Filter to specify minimum value for thirty day total requests. The valid values positive values between 0 to 3000000

Example: thirty_day_total_req_min=120

Response returned will contain thirty_day_total_req greater than or equal to 120

thirty_day_total_req_max Filter to specify maximum value for thirty day total requests. The valid values positive values between 0 to 3000000

Example: thirty_day_total_req_max=120

Response returned will contain thirty_day_total_req less than or equal to 120

thirty_day_total_req_range Filter to specify range value for thirty day total requests. The valid values positive values between 0 to 3000000

Example: thirty_day_total_req_range=120-220

Response returned will contain thirty_day_total_req greater than or equal to 120 and less than or equal to 220

seven_day_unique_req_min Filter to specify minimum value for seven day unique requests. The valid values positive values between 0 to 3000000

seven_day_unique_req_min=100

Response returned will contain seven_day_unique_req greater than or equal to 100

seven_day_unique_req_max Filter to specify maximum value for seven day unique requests. The valid values positive values between 0 to 3000000

seven_day_unique_req_max=100

Response returned will contain seven_day_unique_req less than or equal to 100

seven_day_unique_req_range Filter to specify range value for seven day unique requests. The valid values positive values between 0 to 3000000

Example: seven_day_unique_req_range=120-220

Response returned will contain seven_day_unique_req greater than or equal to 120 and less than or equal to 220

thirty_day_unique_req_min Filter to specify minimum value for thirty day unique requests. The valid values positive values between 0 to 3000000

Example: thirty_day_unique_req_min=100

Response returned will contain thirty_day_unique_req greater than or equal to 100

thirty_day_unique_req_max Filter to specify maximum value for thirty day unique requests. The valid values positive values between 0 to 3000000

Example: thirty_day_unique_req_max=100

Response returned will contain thirty_day_unique_req less than or equal to 100

thirty_day_unique_req_range Filter to specify range value for thirty day unique requests. The valid values positive values between 0 to 3000000

Example: thirty_day_unique_req_range=120-220

Response returned will contain thirty_day_unique_req greater than or equal to 120 and less than or equal to 220

seven_day_business_hour_req_min Filter to specify minimum value for seven day business hour requests. The valid values positive values between 0 to 3000000

Example: seven_day_business_hour_req_min=100

Response returned will contain seven_day_business_hour_req greater than or equal to 100

seven_day_business_hour_req_max Filter to specify maximum value for seven day business hour requests. The valid values positive values between 0 to 3000000

Example: seven_day_business_hour_req_max=100

Response returned will contain seven_day_business_hour_req less than or equal to 100

seven_day_business_hour_req_range Filter to specify range value for seven day business hour requests. The valid values positive values between 0 to 3000000

Example: Example: seven_day_business_hour_req_range=120-220

Response returned will contain seven_day_business_hour_req greater than or equal to 120 and less than or equal to 220

thirty_day_business_hour_req_min Filter to specify minimum value for thirty day business hour requests. The valid values positive values between 0 to 3000000

Example: thirty_day_business_hour_req_min=100

Response returned will contain thirty_day_business_hour_req greater than or equal to 100

thirty_day_business_hour_req_max Filter to specify maximum value for thirty day business hour requests. The valid values positive values between 0 to 3000000

Example: thirty_day_business_hour_req_max=100

Response returned will contain thirty_day_business_hour_req less than or equal to 100

thirty_day_business_hour_req_range Filter to specify range value for thirty day business hour requests. The valid values positive values between 0 to 3000000

Example: thirty_day_business_hour_req_range=120-220

Response returned will contain thirty_day_business_hour_req greater than or equal to 120 and less than or equal to 220

has_numbers Filter to request NXD domains with numbers in searched domain. The valid querying options are true or false

has_numbers=[boolean] i.e [true/false]

True returns NXD domains with alphanumerics and false returns alphabet only domains

has_hyphens Filter to request NXD domains with hyphens in searched domain. The valid querying options are true or false

has_hyphens=[boolean] i.e [true/false]

True returns NXD domains with hyphens in it and false returns non hyphen domains

include_synonyms Filter to request NXD domains containing synonyms for the given keyword. The valid querying options are true or false. This query parameter only works when 'keyword' query parameter is provided and contains only ONE keyword

Example: keyword=honest&include_synonym=true

This will include synonyms of honest in the resulting domain names

tokenize_keyword Filter to request NXD domains based on tokenization of keyword. Keyword will be broken into multiple keywords using english dictionary. The valid querying options are true or false. This query parameter only works when ' keyword ' query parameter is provided and contains only ONE keyword. By default no tokenization happens for a given keyword

Example: keyword=firstdoctor&tokenize_keyword=true

This will include first and doctor as tokenized keywords before searching for domains

domain_name_length_min

Filter to request the minimum length of the domain name (inclusive of number provided)

The domain name length will be limited to 1-63 characters.

Example: domain_name_length_min=15

Only NXD domains with length of 15 or greater will be in the response

domain_name_length_max

Filter to request the maximum length of the domain name (inclusive of number provided)

The domain name length will be limited to 1-63 characters. 

Example: domain_name_length_max=15

Only NXD domains with length of 15 or less will be in the response

domain_name_length_range

Filter to request the range of lengths for the domain name searches

The  domain name length will be limited to 1-63 characters.

Example: domain_name_length_range=15-20

Only domain names having 15 to 20 letters will be in the response

tld Request to filter domains by tld. Valid tlds are com, net, cc, tv

Example : tld=com

Shows only .com domains and rest are excluded

sort_by

sort_by filter helps search results to be sorted on the basis of " domain_name", "domain_name_length".

Use -domain_name and -domain_name_length to sort in descending order

Example: sort_by= domain_name to sort by domain name in ascending order

Example: sort_by=-domain_name_length to sort by domain name length in descending order

page_number Filter used to request the page number of the response. Default page number is 1 and max page number is 100

Example: page_number=10

page_size Filter used to request the page size of the response i.e the total number of domains in each page of results. Specified number of domains are returned in response. Default page size is 50 and max page size is 100 Example: page_size=10
keyword

Filter used to fetch responses based on a keyword. Multiple and a max of 3 keywords can be provided in different combinations listed below.

Character type
Keyword
Description
Space flower shop Multiple keywords can be separated by spaces. All keywords will be contained in the resulting domain names.
* (asterisk)

*shop

shop*

*shop*

Enter a keyword following the * character to search for domain names ending with the keyword.

Enter a keyword before the * character to search for domain names beginning with the keyword.

Enter a keyword surrounded by the * to search for domain names with keyword anywhere in the name.

no sign flowershop

Using nothing in front of a keyword that is a compound word so that it is not split into the individual words.

, comma flower,shop Multiple keywords can be separated by commas; one or more of the keywords will be contained in the resulting domain names.

Example: keyword=flower shop

Flowervirginiashop.com 
Yourflowershop.net

Example: keyword=*shop

onlineshop.com

Example: keyword=flowershop

Yourflowershop.net

Example: keyword=flower,shop

Onlineflowershop.com

Shopyourway.net

 

Success Response

The status code on success is always 200 OK with returned JSON response. All the successful requests will have a JSON response.

Code 200 : OK

Example: /api/v2/domains/nxd?keyword=first&page_size=3

{
  "pagination": {
    "object_count": 16221,
    "page_number": 1,
    "page_size": 3,
    "page_count": 5407
  },
  "domains": [
    {
      "domain_name": "first2know.tv",
      "thirty_day_score": 9.4,
      "seven_day_score": 9.5
    },
    {
      "domain_name": "firstcarrotreaction.tv",
      "thirty_day_score": 4.9,
      "seven_day_score": 6.6
    },
    {
      "domain_name": "firstbankgroup.tv",
      "thirty_day_score": 9.3,
      "seven_day_score": 9.2
    }
  ]
}
Error Response

NXD Endpoints have error responses explaining different failure causes or unavailable results. These failure combinations are explained below

Code 200 : OK ------ Is shown for queries with no results. It's a valid search with no results

Example: /api/v2/domains/nxd?keyword=domainscope&page_size=3

{  }

 

Code 422 : INVALID_ENTITY

Example: /api/v2/domains/nxd?seven_day_score_min=50

{
  "error": "INVALID_ENTITY",
  "error_description": "Invalid parameter value provided. Please ensure seven_day_score_min is at least 0.0 and not exceed 10.0",
  "status_code": 422
}

 

Code 401 : UNAUTHORIZED

401 is the response code if the request is made without a valid key (Please refer to Sample call for making valid authorized request)

API key not present in header, you need API key to access this resource. Contact domainscope@verisign.comfor more details !

 

Code 500 : INTERNAL_SERVER ERROR

Status code 500 is returned when the request is valid but the domainscope cannot process it for unknown reason

 

{
  "error": "INTERNAL_SERVER_ERROR",
  "error_description": "An un-handled error occurred in DomainScope. Contact Domainscope support if this persists. Status code 500.",
  "status_code": 500
}

 

Code 429 : HIT_RATE_LIMIT

Status code 429 is returned when API requests hit the rate limit

Rate Limit exceeded, please try again after 1 min!

 

Code 405 : METHOD_NOT_ALLOWED

Example: /api/v2/domains/nxd?fields=all

{
  "error": "METHOD_NOT_ALLOWED",
  "error_description": "You sent a method : POST to the endpoint it can’t handle (e.g. POST to a GET-only endpoint). Status code 405. Supported methods are : [GET]",
  "status_code": 405
}

 

Code 400 : BAD_REQUEST

Example: /api/v2/domains/nxd?field=all

{
  "error": "BAD_REQUEST",
  "error_description": "Invalid Parameters requested. -> field. Please check the parameters.",
  "status_code": 400
}

 

Code 404 : NOT_FOUND

Example: /api/v2/domain/nxd?fields=all

 

{
  "error": "NOT_FOUND",
  "error_description": "The URL you gave is not valid. Status code 404.",
  "status_code": 404
}
Sample Call

Here is the sample call listed below using CURL to get a valid JSON response. Query parameters can be used in different combinations to obtain optimized response

CURL --header "X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXX" https://domainscope.com/api/v2/domains/nxd\?keyword\=new,job\&fields\=thirty_day_total_req\&page_size\=5 | json_pp
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   662  100   662    0     0   4256      0 --:--:-- --:--:-- --:--:--  4270
{
   "pagination" : {
      "page_number" : 1,
      "object_count" : 158661,
      "page_count" : 31733,
      "page_size" : 5
   },
   "domains" : [
      {
         "domain_name" : "newgraduatejobnetwork.tv"
         "thirty_day_total_req" : 15, ]
 },
      {
         "thirty_day_total_req" : 206,
         "domain_name" : "newjobconcept.com",
      },
      {
         "domain_name" : "itsmynewjob.com",
         "thirty_day_total_req" : 478
      },
      {
         "domain_name" : "new800jobopenings.com",
         "thirty_day_total_req" : 59
      },
      {
         "domain_name" : "crackingthenewjobmarketonline.com",
         "thirty_day_total_req" : 214,
      }
   ]
}

The response above shows that there are 3 default fields(domain_name, seven_day_score, thirty-day_score) that are always returned along with the requested fields

Notes

Format of Response :

A normal 200 : OK response returns 2 objects.

1) pagination : Provides information about results and number of pages it's distributed on

Name
Description
object_count Corresponds to total number of results with the provided search query
page_number The page number of the list of suggestions. This usually corresponds to the page number requested for.
page_size The total number of suggestions in each page of results. This usually corresponds to the page size parameter in the request. The default is 50.
page_count The total number of pages of suggestions.

 

2) domains : Provides array of domain object responses (The default response when no specific fields requested are  domain_name seven_day_score thirty_day_score)

Name
Description
domain_name The actual domain name suggested based on the request criteria
previously_registered

Indicates whether the domain was previously registered or not (yes/no) -

Example: "previously_registered": "no"

thirty_day_total_req

Total number of requests in the past 30 days.

Example: "thirty_day_total_req": 132

seven_day_total_req

Total number of requests in the past 7 days.

Example: "seven_day_total_req": 8

seven_day_score

The 7 day DNS Traffic Score

"seven_day_score": 6.4

thirty_day_score

The 30 day DNS Traffic Score

"thirty_day_score": 8.5

geog_breakout

Breakout of traffic from different geographic regions. This is presented as a comma separated list of phrases, where each phrase has the following format:

"geog_breakout": [
{
"country_code": "CN",
"total_requests": 11,
"unique_requests": 6
}]

In the example above, Geog Breakout object has country code, total requests

seven_day_business_hour_req

Number of Requests during business hours in the past 7 days.

Example: "seven_day_business_hour_req": 3

thirty_day_business_hour_req

Number of Requests during business hours in the past 30 days.

Example: "thirty_day_business_hour_req": 76

is_featured

An indication whether this domain name is a "Featured" domain name. (yes/no)

Example:  "is_featured": "no"

is_idn

Indicates whether domain is an IDN or not (yes/no)

Example: "is_idn": "no"

thirty_day_hourly_req

Hourly breakdown of the number of requests in the past 30 days. The requests are presented as a comma separated list of numbers, one for each hour.

"thirty_day_hourly_req": [0, 0, 0, 0, 2, 7, 6, 16, 7, 12, 15, 7, 9, 18, 4, 7, 11, 2, 3, 2, 0, 0, 0, 0],

seven_day_unique_req

Number of Unique requests in the past 7 days.

Example: "seven_day_unique_req": 8

thirty_day_unique_req

Number of Unique requests in the past 30 days.

Example: "thirty_day_unique_req": 71

is_available

Flag indicating whether the domain is available or not

Example: "is_available": "yes"

The Pending Delete Search API is used to retrieve DNS traffic data and prior website characteristics for recently expired domains. Requests can be made with or without keywords or domain names. Below is the list of request specifications expected by the Pending Delete Search API.

Specification
Spec Description
URL /api/v2/domains/pendingdelete
Method < The request type > : GET
URL Parameters No URL parameters exist for the latest version of Pending delete API. All the filters are accessible through Query String Parameters
Query String Parameters All the parameters supported via Pending delete API uses query string parameters
Required None
Optional
Parameter
Description
Additional Notes
fields Used to limit the response with limited set of fields. Supported fields include one or more of the below: all, domain_name, seven_day_score, thirty_day_score, purpose, monthly_average_domain_rank, monthly_average_us_based_traffic_percent, inbound_links, available_date, available_in, is_idn, brand_safety, website_keywords, monthly_average_popularity_score, monthly_cumulative_traffic_score

Notes

  • If any of these specific fields are requested, only domain_name + the requested set of fields are shown.
  • If 'fields' is not provided as a request parameter, domain_name, seven_day_score and thirty_day_score are shown by default.
Example: fields = [all] responds with all the fields in the response

Example: fields=available_date responds with domain_name and available_date

domain_name is defaulted in response with all the fields requests

domain_names List of domain names can be provided to filter the response based on the domain name. One or more domain names can be provided. Example: domain_names=fivedollarpoker.com, realbooks.com will return the default set of fields for Pending delete response related to fivedollarpoker.com and realbooks.com if available
seven_day_score_min Filter to specify minimum value of DNS traffic seven day score. The valid values are between 0 to 10

Example: seven_day_score_min=7

Response returned will contain seven_day_score greater than 7

seven_day_score_max Filter to specify maximum value of DNS traffic seven day score. The valid values are between 0 to 10

Example: seven_day_score_max=7

Response returned will contain seven_day_score less than 7

seven_day_score_range

Filter to specify range value of DNS traffic seven day score. The valid values are between 0 to 10

Example: seven_day_score_range=8-10

Response returned will contain seven_day_score between 8 to 10

thirty_day_score_min Filter to specify minimum value of DNS traffic thirty day score. The valid values are between 0 to 10  Example: thirty_day_score_min=7

Response returned will contain thirty_day_score greater than or equal to 7

thirty_day_score_max Filter to specify maximum value of DNS traffic thirty day score. The valid values are between 0 to 10

Example: thirty_day_score_max=7

Response returned will contain thirty_day_score less than or equal to 7

thirty_day_score_range Filter to specify range value of DNS traffic thirty day score. The valid values are between 0 to 10

Example: thirty_day_score_range=8-10

Response returned will contain thirty_day_score between 8 to 10

inbound_links_min Filter to specify the minimum number of inbound links to the domain names result. The valid values are between 0 to 1000

Example: /api/v2/domains/pendingdelete?inbound_links_min=100

Responds with Pending delete domains having minimum inbound links of 100

inbound_links_max Filter to specify t he maximum number of inbound links to the domain names result. The valid values are between 0 to 1000

Example: /api/v2/domains/pendingdelete?inbound_links_max=100

Responds with Pending delete domains having maxuimum inbound links of 100

inbound_links_range Filter to specify t he range number for inbound links to the domain names result. The valid values are between 0 to 1000

Example: /api/v2/domains/pendingdelete?inbound_links_range=100-150

Responds with Pending delete domains having range of inbound links between 100 to 150

available_date Filter to mention available date for pending delete domains. The format for date is yyyy-MM-dd format (Make sure the day is from today to next 5 days

Example: available_date=2017-03-17

Shows pending delete domains results that are going to be available 2017-03-17

available_in_min Filter to mention minimum number of days in which the resulted domains are going to be available in

Example: available_in_min=1

Shows domains which are going to be available starting in 1 day

available_in_max Filter to mention maximum number of days in which the resulted domains are going to be available in

Example: available_in_max=1

Shows domains which are going to be available within 1 day (From today to next day)

available_in_range Filter to mention the range of available in days in which the resulted domains are going to be available in. Valid values are between 0 to 5

available_in_range=1-3

Shows domains which are going to be available within the next 1 to 3 days

is_idn Filter to show only IDNs. Absence of filter will return all domains including IDNs and non IDNs. Options are true and false is_idn=[boolean] i.e [true/false]

true will return IDNs and false will return non IDNs

has_numbers Filter to request pending delete domains with numbers in searched domain. The valid querying options are true or false has_numbers=[boolean] i.e [true/false]

True returns domains with alphanumerics and false returns alphabet only domains

has_hyphens Filter to request pending delete domains with hyphens in searched domain. The valid querying options are true or false

has_hyphens=[boolean] i.e [true/false]

True returns domains with hyphens in it and false returns non hyphen domains

include_synonyms Filter to request Pending delete domains containing synonyms for the given keyword. The valid querying options are true or false. This query parameter only works when 'keyword' query parameter is provided and contains only ONE keyword

Example: keyword=honest&include_synonym=true

This will include synonyms of honest in the resulting domain names

tokenize_keyword Filter to request pending delete domains based on tokenization of keyword. Keyword will be broken into multiple keywords using english dictionary. The valid querying options are true or false. This query parameter only works when 'keyword' query parameter is provided and contains only ONE keyword. By default no tokenization happens for a given keyword

Example: keyword=firstdoctor&tokenize_keyword=true

This will include first and doctor as tokenized keywords before searching for domains

domain_name_length_min

Filter to request the minimum length of the domain name (inclusive of number provided)

The domain name length will be limited to 1-63 characters.

Example: domain_name_length_min=15

Only pending delete domains with length of 15 or greater will be in the response

domain_name_length_max

Filter to request the maximum length of the domain name (inclusive of number provided)

The domain name length will be limited to 1-63 characters. 

Example: domain_name_length_max=15

Only Pending delete domains with length of 15 or less will be in the response

domain_name_length_range

Filter to request the range of lengths for the domain name searches

The domain name length will be limited to 1-63 characters.

Example: domain_name_length_range=15-20

Only domain names having 15 to 20 letters will be in the response

tld Request to filter domains by tld. Valid tlds are com, net

Example: tld=com

Shows only .com domains and .net domains are excluded

sort_by

sort_by filter helps search results to be sorted on the basis of "domain_name", "domain_name_length".

Use -domain_name and -domain_name_length to sort in descending order

Example: sort_by=domain_name to sort by domain name in ascending order

Example: sort_by=-domain_name_length to sort by domain name length in desc

page_number Filter used to request the page number of the response. Default page number is 1 and max page number is 100

Example: page_number=10

page_size Filter used to request the page size of the response i.e the total number of domains in each page of results. Specified number of domains are returned in response. Default page size is 50 and max page size is 100 Example: page_size=10
keyword

Filter used to fetch responses based on a keyword. Multiple and a max of 3 keywords can be provided in different combinations listed below.

Character typr
Keyword
Description
Space flower shop Multiple keywords can be separated by spaces. All keywords will be contained in the resulting domain names.
* (asterisk)

*shop

shop*

*shop*

Enter a keyword following the * character to search for domain names ending with the keyword.

Enter a keyword before the * character to search for domain names beginning with the keyword.

Enter a keyword surrounded by the * to search for domain names with keyword anywhere in the name.

no sign flowershop

Using nothing in front of a keyword that is a compound word so that it is not split into the individual words.

, comma flower,shop Multiple keywords can be separated by commas; one or more of the keywords will be contained in the resulting domain names.

Example: keyword=flower shop

Flowervirginiashop.com 
Yourflowershop.net

Example: keyword=*shop

onlineshop.com

Example: keyword=flowershop

Yourflowershop.net

Example: keyword=flower,shop

Onlineflowershop.com

Shopyourway.net

Success Response

The status code on success is always 200 OK with returned JSON response. All the successful requests will have a JSON response.

Code 200 : OK

Example: /api/v2/domains/pendingdelete?keyword=first&page_size=3

{
  "pagination": {
    "object_count": 14123,
    "page_number": 1,
    "page_size": 3,
    "page_count": 4708
  },
  "domains": [
    {
      "domain_name": "firstcitizensonline.cc",
      "thirty_day_score": 4.5,
      "seven_day_score": 6.4
    },
    {
      "domain_name": "firstauctionfactory.tv",
      "thirty_day_score": 5.8,
      "seven_day_score": 6.8
    },
    {
      "domain_name": "firstblood.tv",
      "thirty_day_score": 9,
      "seven_day_score": 9.3
    }
  ]
}
Error Response

Pending delete endpoints have error responses explaining different failure causes or unavailable results. These failure combinations are explained below

 

Code 200 : OK ----- Is shown for queries with no results. It's a valid search with no results

Example: /api/v2/domains/pendingdelete?keyword=domainscope&page_size=3

 

{ }

 

Code 422 : INVALID_ENTITY

Example: /api/v2/domains/pendingdelete?fields=al

 

{
  "error": "INVALID_ENTITY",
  "error_description": "Invalid fields requested -> al",
  "status_code": 422
}

 

Code 401 : UNAUTHORIZED

401 is the response code if the request is made without a valid key (Please refer to Sample call for making valid authorized request)

 

API key not present in header, you need API key to access this resource. Contact domainscope@verisign.com<for more details !

 

Code 500 : INTERNAL_SERVER ERROR

Status code 500 is returned when the request is valid but the domainscope cannot process it for unknown reason.

 

{
  "error": "INTERNAL_SERVER_ERROR",
  "error_description": "An un-handled error occurred in DomainScope. Contact Domainscope support if this persists. Status code 500.",
  "status_code": 500
}

 

Code 429 : HIT_RATE_LIMIT

Status code 429 is returned when API requests hit the rate limit

Rate Limit exceeded, please try again after 1 min!

 

Code 405 : METHOD_NOT_ALLOWED

Example: /api/v2/domains/pendingdelete?fields=all (as a POST call)

{
  "error": "METHOD_NOT_ALLOWED",
  "error_description": "You sent a method : POST to the endpoint it can’t handle (e.g. POST to a GET-only endpoint). Status code 405. Supported methods are : [GET]",
  "status_code": 405
}

 

Code 400 : BAD_REQUEST

Example: api/v2/domains/pendingdelete?fields=all&seven_day_score_rang=3-7

{
  "error": "BAD_REQUEST",
  "error_description": "Invalid Parameters requested. -> seven_day_score_rang. Please check the parameters.",
  "status_code": 400
}

 

Code 404 : NOT_FOUND

Example: /api/v2/domains/pendingdlete?fields=all

{
  "error": "NOT_FOUND",
  "error_description": "The URL you gave is not valid. Status code 404.",
  "status_code": 404
}
Sample Call

Here is the sample call listed below using CURL to get a valid JSON response. Query parameters can be used in different combinations to obtain optimized response

CURL --header "X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXX" https://domainscope.com/api/v2/domains/pendingdelete\?keyword\=new,car\&fields\=is_idn\&page_size\=3\&is_idn\=true | json_pp
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   404  100   404    0     0    464      0 --:--:-- --:--:-- --:--:--   464
{
   "domains" : [
      {
         "thirty_day_score" : 9.1,
         "is_idn" : true,
         "seven_day_score" : 9.3,
         "domain_name" : "cartedecredit-immédiatement.com"
      },
      {
         "thirty_day_score" : 9.4,
         "is_idn" : true,
         "seven_day_score" : 9.7,
         "domain_name" : "carcrédit.com"
      },
      {
         "domain_name" : "baconcariño.com",
         "seven_day_score" : 9,
         "is_idn" : true,
         "thirty_day_score" : 8.9
      }
   ],
   "pagination" : {
      "page_count" : 2,
      "page_size" : 3,
      "object_count" : 5,
      "page_number" : 1
   }
}

The response above is filtered based on keywords having either car or new, with only IDNs in the result and page size of 3

Notes

Format of Response :

A normal 200 : OK response returns 2 objects.

1) pagination : Provides information about results and number of pages it's distributed on

Name
Description
object_count Corresponds to total number of results with the provided search query
page_number The page number of the list of suggestions. This usually corresponds to the page number requested for.
page_size The total number of suggestions in each page of results. This usually corresponds to the page size parameter in the request. The default is 50.
page_count The total number of pages of suggestions.

 

2) domains : Provides array of domain object responses (The default response when no specific fields requested are domain_name, seven_day_score, thirty_day_score)

Name
Description
domain_name The actual domain name suggested based on the request criteria
monthly_cumulative_traffic_score

The monthly cumulative traffic score.

Example: "monthly_cumulative_traffic_score": 502

website_keywords

Terms that best describe the content of the website previously hosted in this domain. The terms are presented as a comma separated list of words.

Example: "website_keywords": [ "website", "unavailable", "owner", "site", "call", "number", "unavailable" ]

monthly_average_popularity_score

The monthly average popularity score.

Example: "monthly_average_popularity_score": 19

monthly_average_us_based_traffic_percent

The monthly average US based traffic share.

Example: "monthly_average_us_based_traffic_percent": 51

purpose An indication of how the website hosted on this domain had been used. The possible values are
  • blog for Blog
  • ecommerce for E-Commerce
  • masked_redirect for Masked Redirect
  • redirect for Redirect
  • real_estate for Real Estate
  • online_business for Online Business
  • other for Other

Example: "purpose": "online_business"

is_idn

Indicates whether domain is an IDN or not

Example: "is_idn": "no"

inbound_links

The number of inbound links to this domain name.

Example: "inbound_links": 0

monthly_average_domain_rank

The monthly average domain rank.

Example: "monthly_average_domain_rank": 78103180

thirty_day_score

The 30 day DNS Traffic Score

Example: "thirty_day_score": 9.5

seven_day_score

The 7 day DNS Traffic Score

Example: "seven_day_score": 9.6

available_date

Date on which the requested domain is going to be available (yyyy-MM-dd)

Example: "available_date": "2017-04-07"

available_in

Shows number of days in which the requested domain will be available

Example: "available_in": 2

brand_safety

A measure of profanity found on the website. High = no profanity during the last 3 months, Medium = profanity during one of the last 3 months, Low = profanity during more than one of the last 3 months.

Example: "brand_safety": "high"

 

 

The Domain Name Lookup API is used to retrieve any data that VERISIGN® DomainScope may have for a domain name, which may include DNS traffic data and/or prior website characteristics. Requests must include domain names, including the TLD extension. A maximum of 100 domain names can be included in each request. Below is the list of request specifications expected by the Domain Name Lookup API.

Specification
Spec Description
URL /api/v2/domains
Method < The request type > : GET
URL Parameters None
Query String Parameters All the parameters supported via Domain Lookup API uses query string parameters
Required
Parameter
Description
Additional Notes
domain_names List of domain names can be provided to filter the response based on the domain name. One or more domain names can be provided

domain_names=justvintagewine.com,rhizomechina.com,thegoatswillrise.com

returns default set of fields for details API. Information available on the three domains is returned. All the fields are shown in response. If no data is available for a particular domain, object with just domain_name is returned

Optional
Parameter
Description
Additional Notes
fields Used to limit the response with limited set of fields. Supported fields include one or more of the below: all, domain_name, seven_day_score, thirty_day_score, is_featured, is_available, previously_registered, is_idn, thirty_day_hourly_req, seven_day_unique_req, thirty_day_unique_req, seven_day_total_req, thirty_day_total_req, seven_day_business_hour_req, thirty_day_business_hour_req, geog_breakout, website_keywords, available_in, available_date, monthly_cumulative_traffic_score, brand_safety, monthly_average_domain_rank, inbound_links, monthly_average_popularity_score, purpose, monthly_average_us_based_traffic_percent

By default, all the fields in the description are returned.

Example: fields=available_date

returns domain_name and available_date for set of domains requested

Success Response

The status code on success is always 200 OK with returned JSON response. All the successful requests will have a JSON response.

Code 200 : OK

Eg: /api/v2/domains?domain_names=justvintagewine.com,thegoatswillrise.com

 

{
  "details_result": [
    {
      "domain_name": "thegoatswillrise.com",
      "thirty_day_unique_req": 244,
      "thirty_day_business_hour_req": 275,
      "seven_day_business_hour_req": 83,
      "seven_day_unique_req": 51,
      "thirty_day_total_req": 564,
      "geog_breakout": [
        {
          "country_code": "US",
          "total_requests": 14,
          "unique_requests": 6
        },
        {
          "country_code": "NL",
          "total_requests": 2,
          "unique_requests": 2
        }
      ],
      "seven_day_total_req": 127,
      "thirty_day_hourly_req": [
        26,
        43,
        15,
        27,
        23,
        27,
        21,
        26,
        15,
        27,
        22,
        13,
        20,
        22,
        35,
        13,
        24,
        18,
        30,
        22,
        15,
        27,
        30,
        23
      ],
      "seven_day_score": 9.7,
      "is_available": "yes",
      "is_idn": "no",
      "thirty_day_score": 9.4,
      "previously_registered": "yes",
      "is_featured": "yes",
      "monthly_average_us_based_traffic_percent": 51,
      "purpose": "ppc",
      "monthly_average_popularity_score": 11,
      "inbound_links": 0,
      "monthly_average_domain_rank": 121663901,
      "brand_safety": "high",
      "monthly_cumulative_traffic_score": 347,
      "available_date": "2017-03-13",
      "available_in": -22,
      "website_keywords": []
    },
    {
      "domain_name": "justvintagewine.com",
      "is_idn": "no",
      "monthly_average_us_based_traffic_percent": 49,
      "thirty_day_score": 9.5,
      "website_keywords": [
        "justvintagewine",
        "vintage",
        "wine",
        "domains",
        "domain",
        "sale",
        "domain",
        "lease",
        "buy",
        "domain",
        "domains",
        "domain",
        "sale"
      ],
      "monthly_average_domain_rank": 54150266,
      "purpose": "ppc",
      "seven_day_score": 9.7,
      "brand_safety": "high",
      "monthly_average_popularity_score": 32,
      "monthly_cumulative_traffic_score": 806,
      "available_date": "2017-04-06",
      "inbound_links": 305,
      "available_in": 2,
      "thirty_day_unique_req": 0,
      "thirty_day_business_hour_req": 0,
      "seven_day_unique_req": 0,
      "seven_day_business_hour_req": 0,
      "thirty_day_total_req": 0,
      "geog_breakout": [],
      "seven_day_total_req": 0,
      "thirty_day_hourly_req": [],
      "is_available": "unknown",
      "previously_registered": "unknown",
      "is_featured": "unknown"
    }
  ]
}
Error Response

Details Endpoints have error responses explaining different failure causes or unavailable results. These failure combinations are explained below

Code 200 : OK ------ Is shown for queries with no results. It's a valid search with no results except domain_name returned back

Eg: /api/v2/domains?domain_names=cnn.com,google.com

{
  "details_result": [
    {
      "domain_name": "cnn.com"
    },
    {
      "domain_name": "google.com"
    }
  ]
}

 

Code 422 : INVALID_ENTITY

Eg: api/v2/domains?domain_names=domain.us

{
  "error": "INVALID_ENTITY",
  "error_description": "Unsupported tld value provided: us",
  "status_code": 422
}

 

Code 401 : UNAUTHORIZED

 401 is the response code if the request is made without a valid key (Please refer to Sample call for making valid authorized request)

 

 

API key not present in header, you need API key to access this resource. Contact domainscope@verisign.comfor more details !

 

Code 500 : INTERNAL_SERVER ERROR

Status code 500 is returned when the request is valid but the domainscope cannot process it for unknown reason.

 

{
  "error": "INTERNAL_SERVER_ERROR",
  "error_description": "An un-handled error occurred in DomainScope. Contact Domainscope support if this persists. Status code 500.",
  "status_code": 500
}

 

Code 429 : HIT_RATE_LIMIT

Status code 429 is returned when API requests hit the rate limit

Rate Limit exceeded, please try again after 1 min!

 

Code 405 : METHOD_NOT_ALLOWED


Example: /api/v2/domains/?domain_names=domainscope.com (POST call)

{
  "error": "METHOD_NOT_ALLOWED",
  "error_description": "You sent a method : POST to the endpoint it can’t handle (e.g. POST to a GET-only endpoint). Status code 405. Supported methods are : [GET]",
  "status_code": 405
}

 

Code 400 : BAD_REQUEST


Eg: /api/v2/domains/

 

{
  "error": "BAD_REQUEST",
  "error_description": "Unable to process request because of the missing query parameter 'domain_names'",
  "status_code": 400
}

 

Code 404 : NOT_FOUND

Eg: /api/v2/domain?domain_names=verisign.com

 

{
  "error": "NOT_FOUND",
  "error_description": "The URL you gave is not valid. Status code 404.",
  "status_code": 404
}

 

 

Sample Call

Here is the sample details call with fields filter.

CURL --header "X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" https://domainscope.com/api/v2/domains\?domain_names\=justvintagewine.com\&fields\=purpose,brand_safety | jsonlint
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    96  100    96    0     0   1259      0 --:--:-- --:--:-- --:--:--  1263
{
  "details_result": [
    {
      "domain_name": "justvintagewine.com",
      "brand_safety": "high",
      "purpose": "ppc"
    }
  ]
}

As in the example above, the default fields domain_name is shown with requested set of fields (i.e purpose and brand_safety)

Notes

Format of Response :

A normal 200 : OK response returns an object details_result with all the fields available by default

Name
Description
domain_name The actual domain name suggested based on the request criteria
thirty_day_unique_req

Number of Unique requests in the past 30 days.

Eg: "thirty_day_unique_req": 71

seven_day_unique_req

Number of Unique requests in the past 7 days.

Eg: "seven_day_unique_req": 8

seven_day_business_hour_req

Number of Requests during business hours in the past 7 days.

Eg: "seven_day_business_hour_req": 3

thirty_day_business_hour_req

Number of Requests during business hours in the past 30 days.

Eg: "thirty_day_business_hour_req": 76

thirty_day_total_req

Total number of requests in the past 30 days.

Eg: "thirty_day_total_req": 132

seven_day_total_req

Total number of requests in the past 7 days.

Eg: "seven_day_total_req": 8

geog_breakout

Breakout of traffic from different geographic regions. This is presented as a comma separated list of phrases, where each phrase has the following format:

"geog_breakout": [
{
"country_code": "CN",
"total_requests": 11,
"unique_requests": 6
}]

In the example above, Geog Breakout object has country code, total requests

thirty_day_hourly_req

Hourly breakdown of the number of requests in the past 30 days. The requests are presented as a comma separated list of numbers, one for each hour.

"thirty_day_hourly_req": [0, 0, 0, 0, 2, 7, 6, 16, 7, 12, 15, 7, 9, 18, 4, 7, 11, 2, 3, 2, 0, 0, 0, 0],

seven_day_score

The 7 day DNS Traffic Score

"seven_day_score": 6.4

thirty_day_score

The 30 day DNS Traffic Score

"thirty_day_score": 8.5

is_available

Flag indicating whether the domain is available or not

Eg: "is_available": "yes"

is_idn

Indicates whether domain is an IDN or not

Eg; "is_idn": "no"

previously_registered

Indicates whether the domain was previously registered or not (yes/no) -

Eg: "previously_registered": "no"

is_featured

Indicates whether this domain name is a "Featured" domain name.

Eg:  "is_featured": "no"

monthly_average_us_based_traffic_percent

The monthly average US based traffic share.

Eg: "monthly_average_us_based_traffic_percent": 51

monthly_average_popularity_score

The monthly average popularity score.

Eg: "monthly_average_popularity_score": 19

monthly_average_domain_rank

The monthly average domain rank.

Eg: "monthly_average_domain_rank": 78103180

monthly_cumulative_traffic_score

The monthly cumulative traffic score.

Eg: "monthly_cumulative_traffic_score": 502

purpose An indication of how the website hosted on this domain had been used. The possible values are
  • blog for Blog
  • ecommerce for E-Commerce
  • masked_redirect for Masked Redirect
  • redirect for Redirect
  • real_estate for Real Estate
  • online_business for Online Business
  • other for Other

Eg: "purpose": "online_business"

inbound_links

The number of inbound links to this domain name.

Eg: "inbound_links": 0

brand_safety

A measure of profanity found on the website. High = no profanity during the last 3 months, Medium = profanity during one of the last 3 months, Low = profanity during more than one of the last 3 months.

Eg: "brand_safety": "high"

available_date

Date on which the requested domain is going to be available (yyyy-MM-dd)

Eg: "available_date": "2017-04-07"

available_in

Shows number of days in which the requested domain will be available

Eg: "available_in": 2

website_keywords

Terms that best describe the content of the website previously hosted in this domain. The terms are presented as a comma separated list of words.

Eg: "website_keywords": [ "website", "unavailable", "owner", "site", "call", "number", "unavailable" ]

The Top Trending Keywords API provides the keywords from recent domain name registrations with the highest growth rates. The number of keywords is configurable for a specified period. .

Specification
Spec Description
URL /api/v2/keywords/trends/top
Method < The request type > : GET
URL Parameters No URL parameters exist for top trending API. All the filters are accessible through Query String Parameters
Query String Parameters All the parameters supported via Top Trending API uses query string parameters
Required

None

Notes:

  • The default frequency is weekly.
  • For weekly frequency, the week over week keywords trending will be shown in the result set.
  • For monthly frequency, the month over month keywords trending will be shown in the result set.
  • The start_date will default to previous week/month based on frequency if no dates are provided.
  • The default samples are limited to 10.
Optional
Parameter
Description
Additional Notes
start_date filter to provide start date requesting keywords trending from that date (yyyy-MM-dd)

Example: start_date=2017-03-03&end_date=2017-03-10

Example: start_date=2017-03-03

end_date

filter to provide end date requesting keywords trending to that date (yyyy-MM-dd)

  • The start date is mandatory if end date is provided.
Example: start_date=2017-03-03&end_date=2017-03-10
num_samples

filter to request indicated number of keywords (number of samples can be between 1 to 100)

Example: start_date=2017-03-03&num_samples=50

frequency filter to include growth through the prior week or month. Valid values are: weekly, monthly Example: num_samples=15&frequency=monthly
Success Response

The status code on success is always 200 OK with returned JSON response. All the successful requests will have a JSON response.

Code 200 : OK

Example: /api/v2/keywords/trends/top?num_samples=3&frequency=weekly

{
  "top_trending_keywords": [
    {
      "keyword": "abarticulations",
      "trend_percent": 81.55,
      "period": "2017-03-19"
    },
    {
      "keyword": "aachens",
      "trend_percent": 80.39,
      "period": "2017-03-19"
    },
    {
      "keyword": "abandonment",
      "trend_percent": 67.66,
      "period": "2017-03-19"
    }
  ]
}
Error Response

Code 200 : OK ----- Is shown for queries with no results. It's a valid search with no results

Example: /api/v2/keywords/trends/top?start_date=2016-03-03&end_date=2016-03-21

{
  "top_trending_keywords": []
}

 

Code 422 : INVALID_ENTITY

Example: /api/v2/keywords/trends/top?start_date=2017-03-03&end_date=2017-03-21&num_samples=1000

{
  "error": "INVALID_ENTITY",
  "error_description": "Please specify num_samples value between 1-100.",
  "status_code": 422
}


Code 401 : UNAUTHORIZED

401 is the response code if the request is made without a valid key (Please refer to Sample call for making valid authorized request)

 

API key not present in header, you need API key to access this resource. Contact domainscope@verisign.comfor more details !


Code 500 : INTERNAL_SERVER ERROR

Status code 500 is returned when the request is valid but the domainscope cannot process it for unknown reason.

 

{
  "error": "INTERNAL_SERVER_ERROR",
  "error_description": "An un-handled error occurred in DomainScope. Contact Domainscope support if this persists. Status code 500.",
  "status_code": 500
}


Code 429 : HIT_RATE_LIMIT

Status code 429 is returned when API requests hit the rate limit

Rate Limit exceeded, please try again after 1 min!

 

Code 405 : METHOD_NOT_ALLOWED

Example: /api/v2/keywords/trends/top (as a POST call)

{
  "error": "METHOD_NOT_ALLOWED",
  "error_description": "You sent a method : POST to the endpoint it can’t handle (e.g. POST to a GET-only endpoint). Status code 405. Supported methods are : [GET]",
  "status_code": 405
}

 

Code 404 : NOT_FOUND

Example: /api/v2/keywords/toptrends

{
  "error": "NOT_FOUND",
  "error_description": "The URL you gave is not valid. Status code 404.",
  "status_code": 404
}
Sample Call

Here is the sample call listed below using CURL to get a valid JSON response. Query parameters can be used in different combinations to obtain filtered response

CURL --header "X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" "https://domainscope.com/api/v2/keywords/trends/top?frequency=monthly&num_samples=2"
 
{
   "top_trending_keywords" : [
      {
         "period" : "2017-02-01",
         "keyword" : "trappist",
         "trend_percent" : 16000
      },
      {
         "period" : "2017-02-01",
         "keyword" : "persisted",
         "trend_percent" : 4300
      }
   ]
}
Notes

Format of Response :

A normal 200 : OK response returns a single flat object

The Keywords Trending Keywords API provides the growth rates for requested keywords for a specified period.

Specification
Spec Description
URL /api/v2/keywords/trends
Method < The request type > : GET
URL Parameters No URL parameters exist for top trending API. All the filters are accessible through Query String Parameters
Query String Parameters All the parameters supported via Top Trending API uses query string parameters
Required

keywords

Notes:

  • The default frequency is weekly.
  • For weekly frequency, the week over week keywords trending will be shown in the result set.
  • For monthly frequency, the month over month keywords trending will be shown in the result set. 
  • The start_date will default to previous week/month based on frequency if no dates are provided.
Optional
Parameter
Description
Additional Notes
keywords Comma separated list of keywords

Example: keywords=shopping

Example: keywords=shopping,arts

start_date filter to provide start date requesting keywords trending from that date (yyyy-MM-dd)

Example: start_date=2017-03-03&end_date=2017- 03-10

Example: start_date=2017-03-03

end_date

filter to provide end date requesting keywords trending to that date (yyyy-MM-dd)

  • The start date is mandatory if end date is provided.
Example: start_date=2017-03-03&end_date=2017- 03-10
frequency filter to include growth through the prior week or month. Valid values are: weekly, monthly Example: num_samples=15&frequency=monthly
Success Response

The status code on success is always 200 OK with returned JSON response. All the successful requests will have a JSON response.

Code 200 : OK

Example: /api/v2/keywords/trends?keywords=abandon,abacas&frequency=weekly

{
  "trending_keywords": [
    {
      "keyword": "abandon",
      "trends": [
        {
          "trend_percent": -19.52,
          "period": "2017-02-19"
        },
        {
          "trend_percent": 68.69,
          "period": "2017-02-26"
        }
      ]
    },
    {
      "keyword": "abacas",
      "trends": [
        {
          "trend_percent": -37.34,
          "period": "2017-02-19"
        },
        {
          "trend_percent": 53.72,
          "period": "2017-02-26"
        }
      ]
    }
  ]
}
Error Response

Code 422 : INVALID_ENTITY

Example: /api/v2/keywords/trends?keywords=qwerty@&start_date=2017-03-03&end_date=2017-03-21

{
  "error": "INVALID_ENTITY",
  "error_description": "Please specify valid keywords value.",
  "status_code": 422
}


Code 401 : UNAUTHORIZED

401 is the response code if the request is made without a valid key (Please refer to Sample call for making valid authorized request)

 

API key not present in header, you need API key to access this resource. Contact domainscope@verisign.comfor more details !


Code 500 : INTERNAL_SERVER ERROR

Status code 500 is returned when the request is valid but the domainscope cannot process it for unknown reason.

 

{
  "error": "INTERNAL_SERVER_ERROR",
  "error_description": "An un-handled error occurred in DomainScope. Contact Domainscope support if this persists. Status code 500.",
  "status_code": 500
}


Code 429 : HIT_RATE_LIMIT

Status code 429 is returned when API requests hit the rate limit

Rate Limit exceeded, please try again after 1 min!

 

Code 405 : METHOD_NOT_ALLOWED

Example: /api/v2/keywords/trends (as a POST call)

{
  "error": "METHOD_NOT_ALLOWED",
  "error_description": "You sent a method : POST to the endpoint it can’t handle (e.g. POST to a GET-only endpoint). Status code 405. Supported methods are : [GET]",
  "status_code": 405
}

 

Code 404 : NOT_FOUND

Example: /api/v2/keywords/toptrends

{
  "error": "NOT_FOUND",
  "error_description": "The URL you gave is not valid. Status code 404.",
  "status_code": 404
}
Sample Call

Here is the sample call listed below using CURL to get a valid JSON response. Query parameters can be used in different combinations to obtain filtered response

{
  "trending_keywords": [
    {
      "keyword": "shopping",
      "trends": [
        {
          "trend_percent": -8.15,
          "period": "2017-01-29"
        },
        {
          "trend_percent": 23.67,
          "period": "2017-02-05"
        },
        {
          "trend_percent": 12.92,
          "period": "2017-02-12"
        },
        {
          "trend_percent": -8.47,
          "period": "2017-02-19"
        }
      ]
    }
  ]
}
Notes

Format of Response :

A normal 200 : OK response returns a single flat object

The Top Popular Keywords API provides the keywords that have been included in recent domain name registrations the most number of times for over a specified period.

Specification
Spec Description
URL /api/v2/keywords/popularity/top
Method < The request type > : GET
URL Parameters No URL parameters exist for top trending API. All the filters are accessible through Query String Parameters
Query String Parameters All the parameters supported via Top Trending API uses query string parameters
Required

None

  • The start_date will default to yesterday if no dates are provided.
  • The default samples are limited to 10.
Optional
Parameter
Description
Additional Notes
start_date filter to provide start date requesting keywords occurrences from that date (yyyy-MM-dd)

Example: start_date=2017-03-03&end_date=2017-03-10

Example: start_date=2017-03-03

end_date

filter to provide end date requesting keywords occurrences to that date (yyyy-MM-dd)

  • The start date is mandatory if end date is provided.
Example: start_date=2017- 03-03&end_date=2017-03-10
num_samples

filter to indicate the number of keywords (number of samples can be between 1 to 100)

Example: start_date=2017-03-03&num_samples=50

Success Response

The status code on success is always 200 OK with returned JSON response. All the successful requests will have a JSON response.

Code 200 : OK

Example: /api/v2/keywords/popularity/top?num_samples=2

{
   "most_popular_keywords":[
      {
         "keyword":"home",
         "total_count":24554,
         "com_count":21763,
         "net_count":2791
      },
      {
         "keyword":"car",
         "total_count":14508,
         "com_count":13950,
         "net_count":558
      }
   ]
}
Error Response

Code 200 : OK ----- Is shown for queries with no results. It's a valid search with no results

Eg : /api/v2/keywords/popularity/top?start_date=2016-03-03&end_date=2016-03-21

{
  "most_popular_keywords": []
}

 

Code 422 : INVALID_ENTITY

Example: /api/v2/keywords/popularity/top?start_date=2017-03-03&end_date=2017-03-21&num_samples=1000

{
  "error": "INVALID_ENTITY",
  "error_description": "Please specify num_samples value between 1-100.",
  "status_code": 422
}


Code 401 : UNAUTHORIZED

401 is the response code if the request is made without a valid key (Please refer to Sample call for making valid authorized request)

 

API key not present in header, you need API key to access this resource. Contact domainscope@verisign.comfor more details !


Code 500 : INTERNAL_SERVER ERROR

Status code 500 is returned when the request is valid but the domainscope cannot process it for unknown reason.

 

{
  "error": "INTERNAL_SERVER_ERROR",
  "error_description": "An un-handled error occurred in DomainScope. Contact Domainscope support if this persists. Status code 500.",
  "status_code": 500
}


Code 429 : HIT_RATE_LIMIT

Status code 429 is returned when API requests hit the rate limit

Rate Limit exceeded, please try again after 1 min!

 

Code 405 : METHOD_NOT_ALLOWED

Example: /api/v2/keywords/popularity/top (as a POST call)

{
  "error": "METHOD_NOT_ALLOWED",
  "error_description": "You sent a method : POST to the endpoint it can’t handle (e.g. POST to a GET-only endpoint). Status code 405. Supported methods are : [GET]",
  "status_code": 405
}

 

Code 404 : NOT_FOUND

Example: /api/v2/keywords/popular/top

{
  "error": "NOT_FOUND",
  "error_description": "The URL you gave is not valid. Status code 404.",
  "status_code": 404
}
Sample Call

Here is the sample call listed below using CURL to get a valid JSON response. Query parameters can be used in different combinations to obtain filtered response

?
 
{
   "most_popular_keywords":[
      {
         "keyword":"home",
         "total_count":24554,
         "com_count":21763,
         "net_count":2791
      },
      {
         "keyword":"car",
         "total_count":14508,
         "com_count":13950,
         "net_count":558
      }
   ]
}
Notes

Format of Response :

A normal 200 : OK response returns a single flat object

The Popular Keywords API provides for the number of times that the requested keywords have been included in recent domain name registrations for a specified period.

Specification
Spec Description
URL /api/v2/keywords/popularity
Method < The request type > : GET
URL Parameters No URL parameters exist for Popular Keywords API. All the filters are accessible through Query String Parameters
Query String Parameters All the parameters supported via Popular Keywords API uses query string parameters
Required

keywords

Notes:

  • The default value for exact_match is true.
  • The start_date will default to previous week/month based on frequency if no dates are provided.
Optional
Parameter
Description
Additional Notes
keywords Comma separated list of keywords

Example: keywords=shopping

Example: keywords=shopping,arts

start_date filter to provide start date requesting keywords trending from that date (yyyy-MM-dd)

Example: start_date=2017-03-03&end_date=2017- 03-10

Example: start_date=2017-03-03

end_date

filter to provide end date requesting keywords trending to that date (yyyy-MM-dd)

  • The start date is mandatory if end date is provided.
Example: start_date=2017-03-03&end_date=2017- 03-10
exact_match filter to control whether to use the exact match or contains query method. Valid values are: true, false Example: keywords=shopping&exact_match=true
Success Response

The status code on success is always 200 OK with returned JSON response. All the successful requests will have a JSON response.

Code 200 : OK

Example: /api/v2/keywords/popularity?keywords=car,flower

{
   "popular_keywords":[
      {
         "keyword":"car",
         "popularity":[
            {
               "total_count":100,
               "period":"2017-02-01"
            },
            {
               "total_count":87,
               "period":"2017-02-02"
            }
         ]
      },
      {
         "keyword":"flower",
         "popularity":[
            {
               "total_count":20,
               "period":"2017-02-01"
            },
            {
               "total_count":46,
               "period":"2017-02-02"
            }
         ]
      }
   ]
}
Error Response

Code 422 : INVALID_ENTITY

Example: /api/v2/keywords/popularity?keywords=qwerty@start_date=2017-03-03end_date=2017-03-21

{
  "error": "INVALID_ENTITY",
  "error_description": "Please specify valid keywords value.",
  "status_code": 422
}


Code 401 : UNAUTHORIZED

401 is the response code if the request is made without a valid key (Please refer to Sample call for making valid authorized request)

 

API key not present in header, you need API key to access this resource. Contact domainscope@verisign.comfor more details !


Code 500 : INTERNAL_SERVER ERROR

Status code 500 is returned when the request is valid but the domainscope cannot process it for unknown reason.

 

{
  "error": "INTERNAL_SERVER_ERROR",
  "error_description": "An un-handled error occurred in DomainScope. Contact Domainscope support if this persists. Status code 500.",
  "status_code": 500
}


Code 429 : HIT_RATE_LIMIT

Status code 429 is returned when API requests hit the rate limit

Rate Limit exceeded, please try again after 1 min!

 

Code 405 : METHOD_NOT_ALLOWED

Example: /api/v2/keywords/popularity (as a POST call)

{
  "error": "METHOD_NOT_ALLOWED",
  "error_description": "You sent a method : POST to the endpoint it can’t handle (e.g. POST to a GET-only endpoint). Status code 405. Supported methods are : [GET]",
  "status_code": 405
}

 

Code 404 : NOT_FOUND

Example: /api/v2/keywords/popular

{
  "error": "NOT_FOUND",
  "error_description": "The URL you gave is not valid. Status code 404.",
  "status_code": 404
}
Sample Call

Here is the sample call listed below using CURL to get a valid JSON response. Query parameters can be used in different combinations to obtain filtered response

 
{
  "popular_keywords": [
    {
      "keyword": "shopping",
      "popularity": [
        {
          "total_count": 21,
          "period": "2017-02-01"
        },
        {
          "total_count": 1889,
          "period": "2017-02-02"
        },
        {
          "total_count": 35,
          "period": "2017-02-03"
        }
      ]
    }
  ]
}
Notes

Format of Response :

A normal 200 : OK response returns a single flat object

Link to VERISIGN® DomainScope API 1.0 documentation can be found here.