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 and Domain Registration History 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. Pending Delete Search
  2. Domain Name Registration History
  3. Domain Name Lookup
  4. Top Trending Keywords
  5. Trending Keywords
  6. Top Popular Keywords
  7. Popular Keywords

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.1/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, 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.
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
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.1/domains/pendingdelete?inbound_links_min=100

Responds with Pending delete domains having minimum inbound links of 100

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

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

Responds with Pending delete domains having maxuimum inbound links of 100

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

Example: /api/v2.1/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.1/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"
    },
    {
      "domain_name": "firstauctionfactory.tv"
    },
    {
      "domain_name": "firstblood.tv"
    }
  ]
}
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.1/domains/pendingdelete?keyword=domainscope&page_size=3

{ }

 

Code 422 : INVALID_ENTITY

Example: /api/v2.1/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.1/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.1/domains/pendingdelete?fields=all&page_numer=2

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

 

Code 404 : NOT_FOUND

Example: /api/v2.1/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 -H 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXX' 'https://domainscope.com/api/v2.1/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" : [
      {
         "is_idn" : true,
         "domain_name" : "cartedecredit-immédiatement.com"
      },
      {
         "is_idn" : true,
         "domain_name" : "carcrédit.com"
      },
      {
         "domain_name" : "baconcariño.com",
         "is_idn" : true
      }
   ],
   "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 is domain_name)

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

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"

Java and PHP Code Examples
package com.yourorg.domainscope.api.client;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClientException;
import org.springframework.web.client.RestTemplate;

public class DomainScopeApiClient {

	private RestTemplate restTemplate = new RestTemplate();

	public void getPendingDelete() {

		String keyHeaderName = "X-DOMAINSCOPE-APIKEY";

		//place API key recieved from	customer support, if you don't have	api key, contact domainscope@verisign.com
		String keyValue = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

		ResponseEntity<String> response;

		// modify this url to add required filters as per your need
		String requestUrl = "https://domainscope.com/api/v2.1/domains/pendingdelete?keyword=new,car&fields=is_idn&page_size=3&is_idn=true";

		try {

			HttpHeaders requestHeaders = new HttpHeaders();
			requestHeaders.set(keyHeaderName, keyValue);
			requestHeaders.set("Accept", "application/json");

			HttpEntity<HttpHeaders> requestEntity = new HttpEntity<HttpHeaders>(null, requestHeaders);

			response = restTemplate.exchange(requestUrl, HttpMethod.GET, requestEntity, String.class);
			System.out.println(response.getBody());

			// recieved correct response, parse this response in your favorite
			// XML/Json parser

		} catch (HttpClientErrorException httpError) {
			System.out.println(httpError.getMessage());

			// error thrown by httpclient, handle according to error code, it
			// could be due to bad request or some other error on server side

		} catch (RestClientException e) {
			System.out.println(e.getMessage());
			// handle error

		} catch (Exception e) {
			System.out.println(e.getMessage());
			// handle error

		}

	}
	
}
<?php
$ch = curl_init();
# set headers 
$headers = array('Accept: application/json', 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');


curl_setopt($ch, CURLOPT_URL, "https://domainscope.com/api/v2.1/domains/pendingdelete?keyword=new,car&fields=is_idn&page_size=3&is_idn=true");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 ); # return into a variable
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers ); # custom headers, see above
$result = curl_exec( $ch ); # run!
curl_close($ch);
print($result);
?>

The Domain Registration History API provides registration history for up to 100 domain names per request. The registration history is NOT provided for domains that either a) have never been registered, or b) are actively registered (for example verisign.com).

Specification
Spec Description
URL /api/v2.1/domains/registrationhistory
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 as a comma-separated list. Up to 100 names can be included in a single query.

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

returns a default set of fields (domain_name and domain_history) for registration history API. Information available on the three domains is returned. domain_name and domain_history 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", "domain_history", "number_of_registration_periods" field, "number_of_total_years_registered" field, "longest_registration_period_days" field, "last_registration_duration_days" field, and "duration_since_last_registration" field, which can be negative for Pending Delete domains.

By default, domain_name and domain_history fields are returned.

Example: fields=number_of_registration_periods

returns domain_name and number_of_registration_periods 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.1/domains/registrationhistory?domain_names=mifeng8.net,lyysgt.com&fields=all

{
  "registration_history": [
    {
      "domain_name": "mifeng8.net",
      "domain_history": [
        {
          "registered_on": "2014-12-01",
          "deleted_on": "2016-01-08",
          "available_on": "2016-02-14"
        }
      ],
      "number_of_registration_periods": 1,
      "number_of_total_years_registered": 1,
      "longest_registration_period_days": 403,
      "last_registration_duration_days": 403,
      "duration_since_last_registration": 631
    },
    {
      "domain_name": "lyysgt.com",
      "domain_history": [
        {
          "registered_on": "2016-08-22",
          "deleted_on": "2017-10-02",
          "available_on": "2017-11-08"
        },
        {
          "registered_on": "2015-06-04",
          "deleted_on": "2016-07-15",
          "available_on": "2016-08-21"
        },
        {
          "registered_on": "2013-03-25",
          "deleted_on": "2015-04-28",
          "available_on": "2015-06-04"
        }
      ],
      "number_of_registration_periods": 3,
      "number_of_total_years_registered": 4,
      "longest_registration_period_days": 764,
      "last_registration_duration_days": 406,
      "duration_since_last_registration": -2
    }
  ]
}
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.1/domains/registrationhistory?domain_names=cnn.com,google.com&fields=all

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

 

Code 422 : INVALID_ENTITY

If any of the query parameters is present but has empty value (e.g. "...?fields=&...") or invalid value (e.g. "...?domain_names=domain.us&..."), a 422 Invalid Entity is returned to the user.

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

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

api/v2.1/domains/registrationhistory?domain_names=anoccasionalstretch.com&fields=

{
    "error": "INVALID_ENTITY",
    "error_description": "The parameter value cannot be empty. Please validate key fields to make sure it's not empty",
    "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.1/domains/registrationhistory?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

The "domain_names" request parameter will be required. If omitted, the user will be returned a 400 Bad Request.

Eg: /api/v2.1/domains/registrationhistory/

{
  "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.1/domains/registration_history?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 -H 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' 'https://domainscope.com/api/v2.1/domains/registrationhistory?domain_names=anoccasionalstretch.com&fields=domain_history,duration_since_last_registration' | json_pp
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100    96  100    96    0     0    1259      0 --:--:-- --:--:-- --:--:--  1263
{
  "registration_history": [
    {
      "domain_name": "anoccasionalstretch.com",
      "domain_history": [
        {
          "registered_on": "2007-11-15",
          "deleted_on": "2010-12-26",
          "available_on": "2011-02-01"
        }
      ],
      "duration_since_last_registration": 2744
    }
  ]
}

As in the example above, the default field domain_name is shown with a requested set of fields (i.e domain_history and duration_since_last_registration)

Notes

Format of Response :

A normal 200 : OK response returns an object registration_history with the domain_name and domain_history fields available by default

Name
Description
domain_name The actual domain name(s) suggested based on the request criteria
domain_history

Array of registration period objects, each of which will have three fields: "registered_on", "deleted_on" and "available_on" containing respective dates

Eg:

"domain_history": [
        {
          "registered_on": "2016-08-22",
          "deleted_on": "2017-10-02",
          "available_on": "2017-11-08"
        },
        {
          "registered_on": "2015-06-04",
          "deleted_on": "2016-07-15",
          "available_on": "2016-08-21"
        },
        {
          "registered_on": "2013-03-25",
          "deleted_on": "2015-04-28",
          "available_on": "2015-06-04"
        }
      ]

number_of_registration_periods

Number of times the domain was registered after being generally available

Eg: "number_of_registration_periods": 3

number_of_total_years_registered

The total number of years the domain was registered

Eg: "number_of_total_years_registered": 4

longest_registration_period_days

Longest number of consecutive days a domain was registered

Eg: "longest_registration_period_days": 764

last_registration_duration_days

Eg: "last_registration_duration_days": 406

duration_since_last_registration

Indicates the number of days since last registered. Note: this can be negative if the domain is in Pending Delete status.

Eg: "duration_since_last_registration": -2

Java and PHP Code Examples
package com.yourorg.domainscope.api.client;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClientException;
import org.springframework.web.client.RestTemplate;

public class DomainScopeApiClient {

	private RestTemplate restTemplate = new RestTemplate();

	public void getRegistrationHistory() {

		String keyHeaderName = "X-DOMAINSCOPE-APIKEY";

		//place API key recieved from	customer support, if you don't have	api key, contact domainscope@verisign.com
		String keyValue = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

		ResponseEntity<String> response;

		// modify this url to add required filters as per your need
		String requestUrl = "https://domainscope.com/api/v2.1/domains/registrationhistory?domain_names=anoccasionalstretch.com&fields=domain_history,duration_since_last_registration";

		try {

			HttpHeaders requestHeaders = new HttpHeaders();
			requestHeaders.set(keyHeaderName, keyValue);
			requestHeaders.set("Accept", "application/json");

			HttpEntity<HttpHeaders> requestEntity = new HttpEntity<HttpHeaders>(null, requestHeaders);

			response = restTemplate.exchange(requestUrl, HttpMethod.GET, requestEntity, String.class);
			System.out.println(response.getBody());

			// recieved correct response, parse this response in your favorite
			// XML/Json parser

		} catch (HttpClientErrorException httpError) {
			System.out.println(httpError.getMessage());

			// error thrown by httpclient, handle according to error code, it
			// could be due to bad request or some other error on server side

		} catch (RestClientException e) {
			System.out.println(e.getMessage());
			// handle error

		} catch (Exception e) {
			System.out.println(e.getMessage());
			// handle error

		}

	}
	
}
<?php
$ch = curl_init();
# set headers 
$headers = array('Accept: application/json', 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');


curl_setopt($ch, CURLOPT_URL, "https://domainscope.com/api/v2.1/domains/registrationhistory?domain_names=anoccasionalstretch.com&fields=domain_history,duration_since_last_registration");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 ); # return into a variable
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers ); # custom headers, see above
$result = curl_exec( $ch ); # run!
curl_close($ch);
print($result);
?>

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.1/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, is_available, previously_registered, is_idn, 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.1/domains?domain_names=justvintagewine.com,thegoatswillrise.com

{
  "details_result": [
    {
      "domain_name": "thegoatswillrise.com",
      "is_available": "no",
      "is_idn": "no",
      "previously_registered": "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-04-04",
      "available_in": 0,
      "website_keywords": []
    },
    {
      "domain_name": "justvintagewine.com",
      "is_idn": "no",
      "monthly_average_us_based_traffic_percent": 49,
      "website_keywords": [
        "justvintagewine",
        "vintage",
        "wine",
        "domains",
        "domain",
        "sale",
        "domain",
        "lease",
        "buy",
        "domain",
        "domains",
        "domain",
        "sale"
      ],
      "monthly_average_domain_rank": 54150266,
      "purpose": "ppc",
      "brand_safety": "high",
      "monthly_average_popularity_score": 32,
      "monthly_cumulative_traffic_score": 806,
      "available_date": "2017-04-06",
      "inbound_links": 305,
      "available_in": 2,
      "is_available": "no",
      "previously_registered": "yes"
    }
  ]
}
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.1/domains?domain_names=cnn.com,google.com

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

 

Code 422 : INVALID_ENTITY

Eg: api/v2.1/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.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.1/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.1/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.1/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 -H 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' 'https://domainscope.com/api/v2.1/domains?domain_names=justvintagewine.com&fields=purpose,brand_safety' | json_pp
  % 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 a 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
is_available

Flag indicating whether the domain is available or not

Eg: "is_available": "no"

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": "yes"

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" ]

Java and PHP Code Examples
package com.yourorg.domainscope.api.client;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClientException;
import org.springframework.web.client.RestTemplate;

public class DomainScopeApiClient {

	private RestTemplate restTemplate = new RestTemplate();

	public void getDomainDetails() {

		String keyHeaderName = "X-DOMAINSCOPE-APIKEY";

		//place API key recieved from	customer support, if you don't have	api key, contact domainscope@verisign.com
		String keyValue = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

		ResponseEntity<String> response;

		// modify this url to add required filters as per your need
		String requestUrl = "https://domainscope.com/api/v2.1/domains?domain_names=justvintagewine.com&fields=purpose,brand_safety";

		try {

			HttpHeaders requestHeaders = new HttpHeaders();
			requestHeaders.set(keyHeaderName, keyValue);
			requestHeaders.set("Accept", "application/json");

			HttpEntity<HttpHeaders> requestEntity = new HttpEntity<HttpHeaders>(null, requestHeaders);

			response = restTemplate.exchange(requestUrl, HttpMethod.GET, requestEntity, String.class);
			System.out.println(response.getBody());

			// recieved correct response, parse this response in your favorite
			// XML/Json parser

		} catch (HttpClientErrorException httpError) {
			System.out.println(httpError.getMessage());

			// error thrown by httpclient, handle according to error code, it
			// could be due to bad request or some other error on server side

		} catch (RestClientException e) {
			System.out.println(e.getMessage());
			// handle error

		} catch (Exception e) {
			System.out.println(e.getMessage());
			// handle error

		}

	}
	
}
<?php
$ch = curl_init();
# set headers 
$headers = array('Accept: application/json', 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');


curl_setopt($ch, CURLOPT_URL, "https://domainscope.com/api/v2.1/domains?domain_names=justvintagewine.com&fields=purpose,brand_safety");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 ); # return into a variable
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers ); # custom headers, see above
$result = curl_exec( $ch ); # run!
curl_close($ch);
print($result);
?>

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.1/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.1/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.1/keywords/trends/top?start_date=2016-03-03&end_date=2016-03-21

{
  "top_trending_keywords": []
}

 

Code 422 : INVALID_ENTITY

Example: /api/v2.1/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.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.1/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.1/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 -H 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' 'https://domainscope.com/api/v2.1/keywords/trends/top?frequency=monthly&num_samples=2' | json_pp
 
{
   "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

Java and PHP Code Examples
package com.yourorg.domainscope.api.client;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClientException;
import org.springframework.web.client.RestTemplate;

public class DomainScopeApiClient {

	private RestTemplate restTemplate = new RestTemplate();

	public void getKeywordTrendsTop() {

		String keyHeaderName = "X-DOMAINSCOPE-APIKEY";

		//place API key recieved from	customer support, if you don't have	api key, contact domainscope@verisign.com
		String keyValue = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

		ResponseEntity<String> response;

		// modify this url to add required filters as per your need
		String requestUrl = "https://domainscope.com/api/v2.1/keywords/trends/top?frequency=monthly&num_samples=2";

		try {

			HttpHeaders requestHeaders = new HttpHeaders();
			requestHeaders.set(keyHeaderName, keyValue);
			requestHeaders.set("Accept", "application/json");

			HttpEntity<HttpHeaders> requestEntity = new HttpEntity<HttpHeaders>(null, requestHeaders);

			response = restTemplate.exchange(requestUrl, HttpMethod.GET, requestEntity, String.class);
			System.out.println(response.getBody());

			// recieved correct response, parse this response in your favorite
			// XML/Json parser

		} catch (HttpClientErrorException httpError) {
			System.out.println(httpError.getMessage());

			// error thrown by httpclient, handle according to error code, it
			// could be due to bad request or some other error on server side

		} catch (RestClientException e) {
			System.out.println(e.getMessage());
			// handle error

		} catch (Exception e) {
			System.out.println(e.getMessage());
			// handle error

		}

	}
	
}
<?php
$ch = curl_init();
# set headers 
$headers = array('Accept: application/json', 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');


curl_setopt($ch, CURLOPT_URL, "https://domainscope.com/api/v2.1/keywords/trends/top?frequency=monthly&num_samples=2");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 ); # return into a variable
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers ); # custom headers, see above
$result = curl_exec( $ch ); # run!
curl_close($ch);
print($result);
?>

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

Specification
Spec Description
URL /api/v2.1/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.1/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.1/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.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.1/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.1/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 -H 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' 'https://domainscope.com/api/v2.1/keywords/trends?keywords=shopping&start_date=2017-02-01&end_date=2017-02-20&frequency=weekly' | json_pp
{
  "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

Java and PHP Code Examples
package com.yourorg.domainscope.api.client;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClientException;
import org.springframework.web.client.RestTemplate;

public class DomainScopeApiClient {

	private RestTemplate restTemplate = new RestTemplate();

	public void getKeywordTrends() {

		String keyHeaderName = "X-DOMAINSCOPE-APIKEY";

		//place API key recieved from	customer support, if you don't have	api key, contact domainscope@verisign.com
		String keyValue = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

		ResponseEntity<String> response;

		// modify this url to add required filters as per your need
		String requestUrl = "https://domainscope.com/api/v2.1/keywords/trends?keywords=shopping&start_date=2017-02-01&end_date=2017-02-20&frequency=weekly";

		try {

			HttpHeaders requestHeaders = new HttpHeaders();
			requestHeaders.set(keyHeaderName, keyValue);
			requestHeaders.set("Accept", "application/json");

			HttpEntity<HttpHeaders> requestEntity = new HttpEntity<HttpHeaders>(null, requestHeaders);

			response = restTemplate.exchange(requestUrl, HttpMethod.GET, requestEntity, String.class);
			System.out.println(response.getBody());

			// recieved correct response, parse this response in your favorite
			// XML/Json parser

		} catch (HttpClientErrorException httpError) {
			System.out.println(httpError.getMessage());

			// error thrown by httpclient, handle according to error code, it
			// could be due to bad request or some other error on server side

		} catch (RestClientException e) {
			System.out.println(e.getMessage());
			// handle error

		} catch (Exception e) {
			System.out.println(e.getMessage());
			// handle error

		}

	}
	
}
<?php
$ch = curl_init();
# set headers 
$headers = array('Accept: application/json', 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');


curl_setopt($ch, CURLOPT_URL, "https://domainscope.com/api/v2.1/keywords/trends?keywords=shopping&start_date=2017-02-01&end_date=2017-02-20&frequency=weekly");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 ); # return into a variable
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers ); # custom headers, see above
$result = curl_exec( $ch ); # run!
curl_close($ch);
print($result);
?>

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.1/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.1/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.1/keywords/popularity/top?start_date=2016-03-03&end_date=2016-03-21

{
  "most_popular_keywords": []
}

 

Code 422 : INVALID_ENTITY

Example: /api/v2.1/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.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.1/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.1/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

CURL -H 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' 'https://domainscope.com/api/v2.1/keywords/popularity/top?start_date=2017-02-01&end_date=2017-02-20&num_samples=2' | json_pp
 
{
   "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

Java and PHP Code Examples
package com.yourorg.domainscope.api.client;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClientException;
import org.springframework.web.client.RestTemplate;

public class DomainScopeApiClient {

	private RestTemplate restTemplate = new RestTemplate();

	public void getPopularityTop() {

		String keyHeaderName = "X-DOMAINSCOPE-APIKEY";

		//place API key recieved from	customer support, if you don't have	api key, contact domainscope@verisign.com
		String keyValue = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

		ResponseEntity<String> response;

		// modify this url to add required filters as per your need
		String requestUrl = "https://domainscope.com/api/v2.1/keywords/popularity/top?start_date=2017-02-01&end_date=2017-02-20&num_samples=2";

		try {

			HttpHeaders requestHeaders = new HttpHeaders();
			requestHeaders.set(keyHeaderName, keyValue);
			requestHeaders.set("Accept", "application/json");

			HttpEntity<HttpHeaders> requestEntity = new HttpEntity<HttpHeaders>(null, requestHeaders);

			response = restTemplate.exchange(requestUrl, HttpMethod.GET, requestEntity, String.class);
			System.out.println(response.getBody());

			// recieved correct response, parse this response in your favorite
			// XML/Json parser

		} catch (HttpClientErrorException httpError) {
			System.out.println(httpError.getMessage());

			// error thrown by httpclient, handle according to error code, it
			// could be due to bad request or some other error on server side

		} catch (RestClientException e) {
			System.out.println(e.getMessage());
			// handle error

		} catch (Exception e) {
			System.out.println(e.getMessage());
			// handle error

		}

	}
	
}
<?php
$ch = curl_init();
# set headers 
$headers = array('Accept: application/json', 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');


curl_setopt($ch, CURLOPT_URL, "https://domainscope.com/api/v2.1/keywords/popularity/top?start_date=2017-02-01&end_date=2017-02-20&num_samples=2");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 ); # return into a variable
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers ); # custom headers, see above
$result = curl_exec( $ch ); # run!
curl_close($ch);
print($result);
?>

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.1/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.1/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.1/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.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.1/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.1/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

CURL -H 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' 'https://domainscope.com/api/v2.1/keywords/popularity?keywords=shopping&start_date=2017-02-01&end_date=2017-02-03' | json_pp
 
{
  "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

Java and PHP Code Examples
package com.yourorg.domainscope.api.client;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClientException;
import org.springframework.web.client.RestTemplate;

public class DomainScopeApiClient {

	private RestTemplate restTemplate = new RestTemplate();

	public void getPopularity() {

		String keyHeaderName = "X-DOMAINSCOPE-APIKEY";

		//place API key recieved from	customer support, if you don't have	api key, contact domainscope@verisign.com
		String keyValue = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";

		ResponseEntity<String> response;

		// modify this url to add required filters as per your need
		String requestUrl = "https://domainscope.com/api/v2.1/keywords/popularity?keywords=shopping&start_date=2017-02-01&end_date=2017-02-03";

		try {

			HttpHeaders requestHeaders = new HttpHeaders();
			requestHeaders.set(keyHeaderName, keyValue);
			requestHeaders.set("Accept", "application/json");

			HttpEntity<HttpHeaders> requestEntity = new HttpEntity<HttpHeaders>(null, requestHeaders);

			response = restTemplate.exchange(requestUrl, HttpMethod.GET, requestEntity, String.class);
			System.out.println(response.getBody());

			// recieved correct response, parse this response in your favorite
			// XML/Json parser

		} catch (HttpClientErrorException httpError) {
			System.out.println(httpError.getMessage());

			// error thrown by httpclient, handle according to error code, it
			// could be due to bad request or some other error on server side

		} catch (RestClientException e) {
			System.out.println(e.getMessage());
			// handle error

		} catch (Exception e) {
			System.out.println(e.getMessage());
			// handle error

		}

	}
	
}
<?php
$ch = curl_init();
# set headers 
$headers = array('Accept: application/json', 'X-DOMAINSCOPE-APIKEY:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');


curl_setopt($ch, CURLOPT_URL, "https://domainscope.com/api/v2.1/keywords/popularity?keywords=shopping&start_date=2017-02-01&end_date=2017-02-03");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1 ); # return into a variable
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers ); # custom headers, see above
$result = curl_exec( $ch ); # run!
curl_close($ch);
print($result);
?>