Instead of ‘login’ and ‘password’ use your credentials from https://app.dataforseo.com/api-access
<?php
// You can download this file from here https://cdn.dataforseo.com/v3/examples/php/php_RestClient.zip
require('RestClient.php');
$api_url = 'https://api.dataforseo.com/';
try {
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
$client = new RestClient($api_url, null, 'login', 'password');
} catch (RestClientException $e) {
echo "\n";
print "HTTP code: {$e->getHttpCode()}\n";
print "Error code: {$e->getCode()}\n";
print "Message: {$e->getMessage()}\n";
print $e->getTraceAsString();
echo "\n";
exit();
}
try {
// using this method you can get a list of locations
// GET /v3/serp/yandex/locations
// in addition to 'yandex' you can also set other search engine
// the full list of possible parameters is available in documentation
$result = $client->get('/v3/serp/yandex/locations');
print_r($result);
// do something with result
} catch (RestClientException $e) {
echo "\n";
print "HTTP code: {$e->getHttpCode()}\n";
print "Error code: {$e->getCode()}\n";
print "Message: {$e->getMessage()}\n";
print $e->getTraceAsString();
echo "\n";
}
$client = null;
?>
The above command returns JSON structured like this:
{
"version": "3.20191128",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.4305 sec.",
"cost": 0,
"tasks_count": 1,
"tasks_error": 0,
"tasks": [
{
"id": "11061103-0696-0120-0000-268044305ce6",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.2547 sec.",
"cost": 0,
"result_count": 94933,
"path": [
"v3",
"serp",
"yandex",
"locations"
],
"data": {
"api": "serp",
"function": "locations",
"se": "yandex"
},
"result": [
{
"location_code": 2840,
"location_name": "United States",
"location_code_parent": null,
"country_iso_code": "US",
"location_type": "Country"
},
{
"location_code": 21132,
"location_name": "Alaska,United States",
"location_code_parent": 2840,
"country_iso_code": "US",
"location_type": "State"
},
{
"location_code": 21133,
"location_name": "Alabama,United States",
"location_code_parent": 2840,
"country_iso_code": "US",
"location_type": "State"
},
{
"location_code": 21135,
"location_name": "Arkansas,United States",
"location_code_parent": 2840,
"country_iso_code": "US",
"location_type": "State"
}
]
}
]
}
You will receive the list of locations by this API call. You can filter the list of locations by country when setting a task.
You can also download the full list of supported locations in the CSV format (last updated 2025-08-05) for:
Note: All locations in Russia and Belarus are no longer supported across all DataForSEO services due to the invasion of Ukraine.
Description of the fields for setting a task:
| Field name | Type | Description |
|---|---|---|
country |
string | country ISO code optional field specify the ISO code if you want to filter the list of locations by country example: us |
As a response of the API server, you will receive JSON-encoded data containing a tasks array with the information specific to the set tasks.
| Field name | Type | Description |
|---|---|---|
version |
string | the current version of the API |
status_code |
integer | general status code you can find the full list of the response codes here |
status_message |
string | general informational message you can find the full list of general informational messages here |
time |
string | execution time, seconds |
cost |
float | total tasks cost, USD |
tasks_count |
integer | the number of tasks in the tasks array |
tasks_error |
integer | the number of tasks in the tasks array returned with an error |
tasks |
array | array of tasks |
id |
string | task identifier unique task identifier in our system in the UUID format |
status_code |
integer | status code of the task generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes here |
status_message |
string | informational message of the task you can find the full list of general informational messages here |
time |
string | execution time, seconds |
cost |
float | cost of the task, USD |
result_count |
integer | number of elements in the result array |
path |
array | URL path |
data |
object | contains the parameters passed in the URL of the GET request |
result |
array | array of results |
location_code |
integer | location code |
location_name |
string | full name of the location |
location_code_parent |
integer | the code of the superordinate location example: "location_code": 9041134,
where
|
country_iso_code |
string | ISO country code of the location |
location_type |
string | location type |

