Getting started
API access and keys
To use the API, you must obtain an API key from the SE Ranking user account. The API key must be transferred via the token parameter for each invoked method or via the Authorization HTTP header. If an API method is invoked without an API key, or if an invalid API key is transferred in the request, the server returns a “no token” or “incorrect token” error.
To get an API key:
1. Log in to the user account.
2. Go to Settings -> API.
3. Click the Generate API Key button.
Making requests
The API is accessible via the HTTPS protocol. All API method invocations are HTTP GET/POST/PUT/DELETE requests to the URL:
https://api4.seranking.com/All received and output data is transmitted via the UTF-8 encoding standard. Data transmitted in the body of the POST/PUT request must be in JSON format.
- If the invocation is done successfully, an HTTP 2xx code is returned.
- If an error occurs, an HTTP 4xx code or an HTTP 5xx code with a description of the error is returned.
Examples (curl)
curl -X GET "https://api4.seranking.com/account/balance" -H "Authorization: Token be2165b7d065e278e7305c1c7ef791f283f5d14b"
HTTP/1.0 200 OK
Content-Type: application/json
{"currency":"rur","value":2296380.85}
------
curl -X GET "https://api4.seranking.com/sites"
HTTP/1.0 403 Forbidden
Content-Type: application/json
{"message":"No token"}
------
curl -X POST "https://api4.seranking.com/sites/" -H "Authorization: Token be2165b7d065e278e7305c1c7ef791f283f5d14b" -d "{\"url\":\"http://example.com\",\"title\":\"example1\"}"
HTTP/1.0 201 Created
Content-Type: application/json
{"site_id":147696}
PHP Example (file_get_contents)
$apiKey = 'API_KEY';
$url = 'https://api4.seranking.com/sites';
$context = stream_context_create([
'http' => [
'method' => 'POST',
'ignore_errors' => true,
'header' => [
"Authorization: Token $apiKey",
"Content-Type: application/json; charset=utf-8"
],
'content' => json_encode([
'url' => 'https://example.com',
'title' => 'my test project'
])
]
]);
$httpStatus = null;
$result = file_get_contents($url, 0, $context);
if (isset($http_response_header)) {
preg_match('`HTTP/[0-9\.]+\s+([0-9]+)`', $http_response_header[0], $matches);
$httpStatus = $matches[1];
}
if (!$result) {
echo "";
} else {
$result = json_decode($result);
if (201 == $httpStatus) {
echo $result->site_id;
} else {
echo 'Error '.$result->message;
}
}
PHP Example (curl)
$url = 'https://api4.seranking.com/sites';
$token = 'API_KEY';
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_HTTPHEADER => ['Authorization: Token '.$token],
CURLOPT_HEADER => 0,
CURLOPT_RETURNTRANSFER => 1,
CURLOPT_POST =>true,
CURLOPT_POSTFIELDS=>json_encode([
'url' => 'https://example.com',
'title' => 'my new test project'
])
]);
$content = curl_exec($curl);
if (!$content) {
echo "Request failed!";
} else {
$info = curl_getinfo($curl);
$result = json_decode($content);
if (201 == $info['http_code']) {
echo $result->site_id;
} else {
echo 'Error '.$result->message;
}
}
Rate limits
To ensure the continuous operation of SE Ranking’s API for all clients, we limit the speed of sending queries. Any API method can be invoked no more than 5 times per second. For example, if a client application makes more than 5 queries per second, the server will return the 429 error code and a message that the application needs to slow down.
If users repeatedly go over the limit on the number of possible queries per second, they will have limited access to the API for 10 minutes. Should the limit be exceeded again in the future, the blocking time will increase.
Error handling
If a request fails, the API returns an appropriate HTTP status code and a textual error message.
For example:
HTTP/1.0 403 Forbidden
Content-Type: application/json
{"message":"No token"}API methods may return the following error codes:
| Code | Summary | Description |
|---|---|---|
400 | Bad Request | Invalid request format. |
400 | Invalid keyword_id | Invalid keyword ID value. |
400 | Invalid date | Invalid date value. |
400 | Invalid site_engine_id | Invalid site engine ID value. |
400 | No ids in request | Required IDs are missing in the request. |
403 | No token | No API key is present in the request. |
403 | Incorrect token | An invalid API key is present in the request. |
403 | No access | Action not available for the current user. |
403 | Access denied | Access to the requested resource is denied. |
404 | Not Found | The resource doesn’t exist for the requested path. |
404 | Unknown search_engine_id | search_engine_id doesn’t exist. |
404 | Unknown site_engine_id | site_engine_id doesn’t exist. |
429 | Too Many Requests | The request rate limit has been exceeded. |
500 | Server error | Internal server error. |
