Getting started

To access the API you need API credentials, which consist of an API key (username) and API secret (password).

Step 1: After login, you can easily generate your API credentials in your account settings.

Step 2: Use the button labeled "create new API key" to instantly create your API Key & Secret.

We recommend using different API credentials for different applications to have separate access control at any time. You can create up to 10 API keys. These can be individually suspended in the API key administration. Suspended credentials can be deleted permanently or reactivated at any time

IMPORTANT: Your API secret is used as public key, meaning it authorizes you when performing an API call. Since every API call uses credits, the secret must be kept private and protected against third party access.


Basic structure of an API Request

For querying the API a HTTP request is sent which will deliver data in JSON as return format. All API calls are authenticated and authorized using a 2-legged OAuth mechanism which is sent in the header of the HTTP request. For this, you are free to use any OAuth library for your language, which is able to send valid OAuth signed requests. However, we recommend using our SDK for PHP, as it will handle all this for you.

Every API call requires values for one or several parameters, e.g. a specification of URL, keyword etc.

For instance, if you want to query "Searchmetrics SEO World Visibility" (an indicator for the visibility of a page in Google taking into account the number of ranked keywords incl. their positions and search volumes) for the domain SEARCHMETRICS.COM, the only required parameter is the domain, so you simply call this URL:

http://api.searchmetrics.com/v1/ResearchOrganicGetValueSeoVisibilityWorld.json?url=searchmetrics.com

The use of parameters is simple:

  • Start specifying parameters after the ? in the http-call.
  • The value for a parameter is defined in the following format: parameter=value
  • If an API call has several parameters, separate them with &
  • If a parameter is an array please separate the values with a comma without blank: parameter=value1,value2

The result is then delivered in JSON format. For the example, the call above would return only one value, the visibility:

	{
		"sum": 2085245
	}
	

For a list of all available API queries please check our API query overview.


SDK

For authentification we are offering an SDK in PHP. So far it does only support HTTP and not yet HTTPS.

Please note:

  • The methods within the SDK are always named in the structure "get" + [nameofthecall], e.g. "getResearchOrganicGetValueSeoVisibility".
  • When creating a call within the SDK the order of the parameters entered is critical. The correct order of the parameters can be found in the SDK itself in the class "SearchmetricsAPI.php" in the respective method. In case you are using an IDE it will show you the correct order as well.

Example

		<?
		// include main class file
		require_once 'SearchmetricsAPI.php';

		// create a new api client instance
		// use your API credentials from your essentials account settings
		// http://suite.searchmetrics.com/en/settings/profile
		$api_key = 'YOUR_API_KEY_GOES_HERE';
		$api_secret = 'YOUR_API_SECRET_GOES_HERE';

		// optional, set the timeout for this API call
		$timeout = 30;

		$api = new SearchmetricsAPI($api_key, $api_secret, $timeout);

		try
		{
			$result = $api->'NAME_OF_API_CALL_GOES_HERE'("PARAMETER1_GOES_HERE_FOR_INSTANCE_CNNDOTCOM", "PARAMETER2_GOES_HERE_FOR_INSTANCE_US");
			var_dump($result);
		}
		catch (Exception $e)
		{
			print $e->getMessage();
		}
	

The required parameters and their required order for the statement

$result = $api->'NAME_OF_API_CALL_GOES_HERE'("PARAMETER1_GOES_HERE_FOR_INSTANCE_CNNDOTCOM", "PARAMETER2_GOES_HERE_FOR_INSTANCE_US");

can be found via the IDE or alternatively be looked up directly in the class "SearchmetricsAPI.php" within the SDK.

Please note our SDK license.

Implementation without SDK

If you do not want to use our SDK and therefore implement the signing and handling of your OAuth requests yourself or want to use an external OAuth-tool, please note the following important points:

  • We are using a 2-legged OAuth without token. So in case your authentication procedure requires a token you can leave the fields blank.
  • Most Oauth tools require the following parameters
    'version' => '1.0',
    'signatureMethod' => "HMAC-SHA1",
    'consumerKey' => $your_api_key_goes_here,
    'consumerSecret' => $your_api_secret_goes_here
  • Whatever tool you are using, the final header that is sent must look similar to this one (keys are faked and do not work):
    Authorization: OAuth oauth_signature="XSnlog6pfaxDTaiACA7tyXt1xU4%3D", oauth_version="1.0", oauth_nonce="9c2fc8ce_0d71_4bb9_8cce_8273f41f1a5e", oauth_consumer_key="2084841506a494a710bb3d47a340dca94c06fa62", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1363949097"
  • In case you want to generate the nonce yourself please do only use the following characters: [a-z], [A-Z], [0-9]

		<?
		$api_key	= 'YOUR_API_KEY_HERE';
		$api_secret = 'YOUR_API_SECRET_HERE';

		$oauthOptions = array(
			'requestScheme' => Zend_Oauth::REQUEST_SCHEME_HEADER,
			'version' => '1.0',
			'signatureMethod' => "HMAC-SHA1",
			'consumerKey' => $api_key,
			'consumerSecret' => $api_secret
		);
		// Token is empty, because we are using 2-legged OAuth
		$token = new Zend_Oauth_Token_Access();

		$client = $token->getHttpClient($oauthOptions);
		$client->setUri('HTTP_CALL_GOES_HERE');
		$client->setMethod(Zend_Http_Client::GET);
		$client->setParameterGet('NAME_OF_PARAMETER1_GOES_HERE_FOR_INSTANCE_URL', 'PARAMETER1_GOES_HERE_FOR_INSTANCE_EBAY.COM'. 'NAME_OF_PARAMETER2_GOES_HERE_FOR_INSTANCE_COUNTRYCODE', 'PARAMETER2_GOES_HERE_FOR_INSTANCE_US');
		$client->setConfig(array('timeout' => 30));
		$response = $client->request();

		print_r($response->getBody());
	

API query optimization

Currently the number of requests per hour are limited to a level that should be sufficient for most use cases. However, if you receive error messages that for some reason your rate limit was exceeded you can consider optimizing the scheduling of your queries:

  • Shift your queries to nighttime/weekend hours. We usually allow higher request rate limits during these times due to lower overall number of requests
  • Shift your queries to uncommon times, e.g. 17:43:30 instead of 17:00:00

If you persist in experiencing performance problems, please contact your personal support contact, which can be found here.

We are curious to hear about your project and will find solutions to make your API project successful.


Legal

The usage of data provided by the Searchmetrics API for commercial and other third-party services without the explicit authorization of Searchmetrics is strictly prohibited.

Publication of data provided by the API must come with a reference to Searchmetrics, publication of data without mentioning the source is strictly prohibited.

Please note our terms and conditions:



License for Searchmetrics SDK

Copyright (c) 2011, Searchmetrics GmbH, Berlin, Germany
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

- Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
- Neither the name of the Searchmetrics GmbH nor the
names of its contributors may be used to endorse or promote products
derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL SEARCHMETRICS GMBH BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.