Getting Started
API Access & Keys
In order to use the API, it is necessary to 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.
Getting an API key
In order to start using the API, you must:
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 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 & Quotas
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
In case of an error, the server returns its HTTP code and a textual error message.
Example
HTTP/1.0 403 Forbidden
Content-Type: application/json
{“message”:”No token”}
All API methods can return the following error codes:
500 Server error
Internal server error
400 Bad Request
Invalid request format
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
403 Access denied
Access to the resource is denied
404 Not Found
The resource does not exist for the requested path
429 Too Many Requests
The limit on the number of requests has been exceeded