Skip to main content

API Management

  • Updated

API is the abbreviation for Application Programming Interface. This is where different programs are connected to each other so that data can be exchanged between these systems. 

In order to allow and protect such data exchange, passwords are required. These are called API Keys and Shared Secrets and serve as a login to deny unauthorized persons access to the data. 

With the help of these keys, commands are sent from other systems to the Searchmetrics database so that it shares the requested information.

Currently data in the following categories is available:

  • Organic Search rankings and visibility
  • Paid Search rankings and visibility
  • Keywords

API & Export credits are calculated for each call. The exact cost of a call is specified in the call description. Calls that include historical or filtered data are usually a bit more expensive.

A documentation of all commands (API Calls) can be found here: Searchmetrics API Documentation.

 

Content


Create an API Key in the Searchmetrics Suite

Under Settings > API Keys > Overview API Keys can be created for various purposes. The API Keys are used to send commands to the Searchmetrics database from other systems to share the requested information.

Click on "create new API Key" on the upper right corner. Enter the desired name and select the license where the key should be located, In the field that opens. 

APIkeyerstellen.png

 

The table below lists all API Keys and respective Shared Secrets. Additionally, the already used and commonly available API Credits can be viewed here. Take a look at the License Management article to learn how to distribute resources across different licenses.

tableAPI.JPG

 

Recommendation: Create separate API keys for every sublicense to control the access to data and to evaluate the access afterwards. You can set up to 10 API Keys here.

APIEN.png

 

Get the access token

The tokens can be generated using the API key and the shared secret. First open a shell (e.g. CMD for Windows / Terminal for Apple).

Insert your API Key and the Shared Secret into the corresponding gaps and remove the "<" ">" characters.

curl -u : https://api.searchmetrics.com/v4/token -d "grant_type=client_credentials"

 

In a script, insert the two specifications of the following dimensions:



$api_key = '';
$api_secret = '';

$url = 'https://api.searchmetrics.com/v4/';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,               $url . 'token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER,    true);
curl_setopt($ch, CURLOPT_HEADER,            false);
curl_setopt($ch, CURLOPT_POST,              true);
curl_setopt($ch, CURLOPT_POSTFIELDS,        'grant_type=client_credentials');
curl_setopt($ch, CURLOPT_USERPWD,           $api_key.':'.$api_secret);
$result = curl_exec($ch);
curl_close($ch);

$result = json_decode($result, true);
$access_token = $result['access_token'];

 

Then you will receive the token in the following field:

{
    "access_token": "",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": null
}


This token is now valid for 60 mins and can be used for API calls.

 

Make an API Call

Let's look at an example. We want to know the value of global organic SEO visibility for searchmetrics.com.

  • From the documentation we take the call: ResearchOrganicGetValueSeoVisibilityWorld
  • The project ID can be found in the address bar in the Searchmetrics Suite: project_id=xxxxxxx
  • The search engine ID can also be found in the documentation > Admin > Search Engines.
  • We created the token in the previous step. 

Now we have defined all sizes and can start the call.



$project_id = <your_project_id>;
$se_id = <searchengine_id>;

$url = 'https://api.searchmetrics.com/v4/';
// Name of the call
$url .= 'ResearchOrganicGetValueSeoVisibilityWorld.json');
// Needed parameter
$url .= '?url=searchmetrics.com';
// Don't forget the token
$url .= '&access_token=<your_access_token>');

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,               $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER,    true);
curl_setopt($ch, CURLOPT_HEADER,            false);
$result = curl_exec($ch);
curl_close($ch);

$result = json_decode($result, true);

 

The result should be output in the following format. The global SEO visibility of the given URL in our example is 2,085,245.

{
    "sum": 2085245
}

 

You can easily get assistance in creating the code. To do this, select a call in our documentation. On the top of each page you will find the cost of the call and the parameters that are needed. The token is always needed.

Let's look at this again with an example: We want to know the number of all organic keywords for our domain. So we search under Research Cloud > Organic and find GetCountOrganicKeyword.

On this page we learn that this call costs 50 API credits. And that the country code, as well as the URL is needed to start the call.

Further down the page, the requested parameters can be put in the blanks. Then click on "Send" and receive the response directly on this page.

API_call.JPG

>> Click here for the complete Getting Started Guide in the developer documentation!