Instead of ‘login’ and ‘password’ use your credentials from https://app.dataforseo.com/api-dashboard
<?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-dashboard
$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 {
$result = array();
// #1 - using this method you can get a list of completed tasks
// GET /v3/serp/{{low_se_name}}/{{low_se_type}}/tasks_ready
// in addition to '{{low_se_name}}' and '{{low_se_type}}' you can also set other search engine and type parameters
// the full list of possible parameters is available in documentation
$tasks_ready = $client->get('/v3/serp/{{low_se_name}}/{{low_se_type}}/tasks_ready');
// you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if (isset($tasks_ready['status_code']) AND $tasks_ready['status_code'] === 20000) {
foreach ($tasks_ready['tasks'] as $task) {
if (isset($task['result'])) {
foreach ($task['result'] as $task_ready) {
// #2 - using this method you can get results of each completed task
// GET /v3/serp/{{low_se_name}}/{{low_se_type}}/task_get/advanced/$id
if (isset($task_ready['endpoint_advanced'])) {
$result[] = $client->get($task_ready['endpoint_advanced']);
}
// #3 - another way to get the task results by id
// GET /v3/serp/{{low_se_name}}/{{low_se_type}}/task_get/advanced/$id
/*
if (isset($task_ready['id'])) {
$result[] = $client->get('/v3/serp/{{low_se_name}}/{{low_se_type}}/task_get/advanced/' . $task_ready['id']);
}
*/
}
}
}
}
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": "0.1.20230705",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0493 sec.",
"cost": 0,
"tasks_count": 1,
"tasks_error": 0,
"tasks": [
{
"id": "08021543-1535-0066-0000-bcbd9fbff47a",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0156 sec.",
"cost": 0,
"result_count": 1,
"path": [
"v3",
"serp",
"google",
"maps",
"task_get",
"advanced",
"08021543-1535-0066-0000-bcbd9fbff47a"
],
"data": {
"api": "serp",
"function": "task_get",
"se": "google",
"se_type": "maps",
"language_code": "en",
"keyword": "albert einstein",
"location_code": 2840,
"depth": 3,
"device": "desktop",
"os": "windows"
},
"result": [
{
"keyword": "albert einstein",
"type": "maps",
"se_domain": "google.com",
"location_code": 2840,
"language_code": "en",
"check_url": "https://google.com/maps/search/albert+einstein/@37.09024,-95.712891,4z?hl=en&gl=US&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc",
"datetime": "2023-08-02 12:43:05 +00:00",
"spell": null,
"item_types": [
"maps_search"
],
"se_results_count": 0,
"items_count": 3,
"items": [
{
"type": "maps_search",
"rank_group": 1,
"rank_absolute": 1,
"domain": null,
"title": "Albert Einstein Statue",
"url": null,
"contact_url": null,
"rating": null,
"rating_distribution": null,
"snippet": "6700 NW 35th St, Bethany, OK 73008",
"address": "6700 NW 35th St, Bethany, OK 73008",
"address_info": {
"borough": "Central Oklahoma City",
"address": "6700 NW 35th St",
"city": "Bethany",
"zip": "73008",
"region": "Oklahoma",
"country_code": "US"
},
"place_id": "ChIJSe0feYkFsocRajueupcvpas",
"phone": null,
"main_image": "https://lh5.googleusercontent.com/p/AF1QipOfM59_liNdL9hmEDbU0_K1uTSv4psbY7rY2bAj=w408-h541-k-no",
"total_photos": 12,
"category": "Tourist attraction",
"additional_categories": null,
"category_ids": [
"tourist_attraction"
],
"work_hours": {
"timetable": null,
"current_status": "close"
},
"feature_id": "0x87b20589791fed49:0xaba52f97ba9e3b6a",
"cid": "12368344280360434538",
"latitude": 35.5064351,
"longitude": -97.6317255,
"is_claimed": false,
"local_justifications": null,
"is_directory_item": false,
"price_level": null,
"hotel_rating": null
},
{
"type": "maps_search",
"rank_group": 2,
"rank_absolute": 2,
"domain": "www.alberteinsteingroup.com",
"title": "The Albert Einstein Group, Inc.",
"url": "http://www.alberteinsteingroup.com/",
"contact_url": null,
"rating": {
"rating_type": "Max5",
"value": 4,
"votes_count": 4,
"rating_max": null
},
"rating_distribution": {
"1": 1,
"2": 0,
"3": 0,
"4": 0,
"5": 3
},
"snippet": "8710 Converse Business Cir, Converse, TX 78109",
"address": "8710 Converse Business Cir, Converse, TX 78109",
"address_info": {
"borough": "Northeast Side",
"address": "8710 Converse Business Cir",
"city": "Converse",
"zip": "78109",
"region": "Texas",
"country_code": "US"
},
"place_id": "ChIJ5QKOJR6KXIYRm3-tvYC0RuE",
"phone": "+1833-463-3325",
"main_image": "https://lh5.googleusercontent.com/p/AF1QipMwYCFGMituQ_CohAgfNF6pQPNjt-b-FR96b7xc=w416-h240-k-no",
"total_photos": 18,
"category": "Business to business service",
"additional_categories": null,
"category_ids": [
"business_to_business_service"
],
"work_hours": {
"timetable": {
"sunday": null,
"monday": [
{
"open": {
"hour": 8,
"minute": 0
},
"close": {
"hour": 17,
"minute": 0
}
}
],
"tuesday": [
{
"open": {
"hour": 8,
"minute": 0
},
"close": {
"hour": 17,
"minute": 0
}
}
],
"wednesday": [
{
"open": {
"hour": 8,
"minute": 0
},
"close": {
"hour": 17,
"minute": 0
}
}
],
"thursday": [
{
"open": {
"hour": 8,
"minute": 0
},
"close": {
"hour": 17,
"minute": 0
}
}
],
"friday": [
{
"open": {
"hour": 8,
"minute": 0
},
"close": {
"hour": 17,
"minute": 0
}
}
],
"saturday": [
{
"open": {
"hour": 8,
"minute": 0
},
"close": {
"hour": 12,
"minute": 0
}
}
]
},
"current_status": "close"
},
"feature_id": "0x865c8a1e258e02e5:0xe146b480bdad7f9b",
"cid": "16232860371934609307",
"latitude": 29.515755199999997,
"longitude": -98.3017169,
"is_claimed": true,
"local_justifications": null,
"is_directory_item": false,
"price_level": null,
"hotel_rating": null
},
{
"type": "maps_search",
"rank_group": 3,
"rank_absolute": 3,
"domain": null,
"title": "Albert Einstein Statue",
"url": null,
"contact_url": null,
"rating": {
"rating_type": "Max5",
"value": 4.7,
"votes_count": 14,
"rating_max": null
},
"rating_distribution": {
"1": 0,
"2": 0,
"3": 1,
"4": 2,
"5": 11
},
"snippet": "172 Gore Creek Dr, Vail, CO 81657",
"address": "172 Gore Creek Dr, Vail, CO 81657",
"address_info": {
"borough": null,
"address": "172 Gore Creek Dr",
"city": "Vail",
"zip": "81657",
"region": "Colorado",
"country_code": "US"
},
"place_id": "ChIJy2EyO2xwaocRcwmC0WGy9jM",
"phone": null,
"main_image": "https://lh5.googleusercontent.com/p/AF1QipPzOIua4GVc8oLCTCNT6nkDZr369gpxVFPnkcOC=w408-h306-k-no",
"total_photos": 10,
"category": "Sculpture",
"additional_categories": [
"Tourist attraction"
],
"category_ids": [
"sculpture",
"tourist_attraction"
],
"work_hours": {
"timetable": {
"sunday": [
{
"open": {
"hour": 0,
"minute": 0
},
"close": {
"hour": 0,
"minute": 0
}
}
],
"monday": [
{
"open": {
"hour": 0,
"minute": 0
},
"close": {
"hour": 0,
"minute": 0
}
}
],
"tuesday": [
{
"open": {
"hour": 0,
"minute": 0
},
"close": {
"hour": 0,
"minute": 0
}
}
],
"wednesday": [
{
"open": {
"hour": 0,
"minute": 0
},
"close": {
"hour": 0,
"minute": 0
}
}
],
"thursday": [
{
"open": {
"hour": 0,
"minute": 0
},
"close": {
"hour": 0,
"minute": 0
}
}
],
"friday": [
{
"open": {
"hour": 0,
"minute": 0
},
"close": {
"hour": 0,
"minute": 0
}
}
],
"saturday": [
{
"open": {
"hour": 0,
"minute": 0
},
"close": {
"hour": 0,
"minute": 0
}
}
]
},
"current_status": "open"
},
"feature_id": "0x876a706c3b3261cb:0x33f6b261d1820973",
"cid": "3744376273401678195",
"latitude": 39.64065,
"longitude": -106.37506669999999,
"is_claimed": false,
"local_justifications": null,
"is_directory_item": false,
"price_level": null,
"hotel_rating": null
}
]
}
]
}
]
}
Description of the fields for sending a request:
| Field name | Type | Description |
|---|---|---|
id |
string | task identifier a universally unique identifier (UUID) unique task identifier in our system you will be able to use it within 30 days to request the results of the task at any time |
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.
Description of the fields in the results array:
| 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 Note: we strongly recommend designing a necessary system for handling related exceptional or error conditions |
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 same parameters that you specified in the POST request |
result |
array | array of results |
keyword |
string | keyword received in a POST array the keyword is returned with decoded %## (plus symbol ‘+’ will be decoded to a space character) |
type |
string | search engine type in a POST array |
se_domain |
string | search engine domain in a POST array |
location_code |
integer | location code in a POST array |
language_code |
string | language code in a POST array |
check_url |
string | direct URL to search engine results you can use it to make sure that we provided exact results Note: to check location-specific results, follow the provided check url, scroll up and down, then click the “Search this area” button |
datetime |
string | date and time when the result was received in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00” example: 2019-11-15 12:57:46 +00:00 |
spell |
object | autocorrection of the search engine if the search engine provided results for a keyword that was corrected, we will specify the keyword corrected by the search engine and the type of autocorrection |
keyword |
string | keyword obtained as a result of search engine autocorrection the results will be provided for the corrected keyword |
type |
string | type of autocorrection possible values: did_you_mean, showing_results_for, no_results_found_for, including_results_for |
item_types |
array | types of search results in SERP contains types of search results ( items) found in SERP.possible item types: maps_search, maps_paid_item |
se_results_count |
integer | total number of results in SERP |
items_count |
integer | the number of results returned in the items array |
items |
array | elements of search results found in SERP |
| ‘Google Maps’ SERP element | ||
type |
string | type of element = ‘maps_search’ |
rank_group |
integer | group rank in SERP position within a group of elements with identical type valuespositions of elements with different type values are omitted from rank_group |
rank_absolute |
integer | absolute rank in SERP absolute position among all the elements in SERP |
domain |
string | domain in the SERP element |
title |
string | title of the result in SERP |
url |
string | relevant URL in SERP |
contact_url |
string | URL of the preferred contact page |
rating |
object | the element’s rating the popularity rate based on reviews and displayed in SERP |
rating_type |
string | the type of rating here you can find the following elements: Max5, Percents, CustomMax |
value |
integer | the value of the rating |
votes_count |
integer | the amount of feedback |
rating_max |
integer | the maximum value for a rating_type |
rating_distribution |
object | the distribution of ratings of the business entity the object displays the number of 1-star to 5-star ratings, as reviewed by users |
1 |
integer | the number of 1-star ratings |
2 |
integer | the number of 2-star ratings |
3 |
integer | the number of 3-star ratings |
4 |
integer | the number of 4-star ratings | 5 |
integer | the number of 5-star ratings |
snippet |
string | element snippet contains the address and other information about the local establishment featured in the element |
address |
string | address line address of the local establishment featured in the element |
address_info |
object | object containing address components of the local establishment |
borough |
string | administrative unit or district the local establishment belongs to |
address |
string | street address of the local establishment |
city |
string | name of the city where the local establishment is located |
zip |
string | ZIP code of the local establishment |
region |
string | DMA region the local establishment belongs to |
country_code |
string | ISO country code of the local establishment |
place_id |
string | unique place identifier place id of the local establishment featured in the element |
phone |
string | phone number phone number of the local establishment featured in the element |
main_image |
string | URL of the main image featured in Google My Business profile |
total_photos |
integer | total count of images featured in Google My Business profile |
category |
string | business category Google My Business general category that best describes the services provided by the business entity |
additional_categories |
array | additional business categories additional Google My Business categories that describe the services provided by the business entity in more detail |
category_ids |
array | global category IDs universal category IDs that do not change based on the selected country |
work_hours |
object | open hours information about work hours of the local establishment |
timetable |
object | work hours timetable |
sunday |
array | work hours on Sundays |
open |
object | opening time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
close |
object | closing time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
monday |
array | work hours on Mondays |
open |
object | opening time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
close |
object | closing time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
tuesday |
array | work hours on Tuesdays |
open |
object | opening time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
close |
object | closing time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
wednesday |
array | work hours on Wednesdays |
open |
object | opening time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
close |
object | closing time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
thursday |
array | work hours on Thursdays |
open |
object | opening time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
close |
object | closing time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
friday |
array | work hours on Fridays |
open |
object | opening time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
close |
object | closing time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
saturday |
array | work hours on Saturday |
open |
object | opening time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
close |
object | closing time |
hour |
integer | hours in the 24-hour format |
minute |
integer | minutes |
current_status |
string | current status of the establishment indicates whether the establishment is opened or closed |
feature_id |
string | the unique identifier of the element in SERP |
cid |
string | google-defined client id unique id of a local establishment; can be used with Google Reviews API to get a full list of reviews |
latitude |
float | latitude coordinate of the local establishments in google maps example: "latitude": 51.584091 |
longitude |
float | longitude coordinate of the local establishment in google maps example: "longitude": -0.31365919999999997 |
is_claimed |
boolean | indicates whether ownership of this local establishment is claimed |
local_justifications |
array | Google local justifications snippets of text that “justify” why the business is showing up for search query |
type |
string | type of local justification posible values: "user_review","website_mention","menu","other"
|
text |
string | text snippet of local justification |
is_directory_item |
boolean | indicates whether this local establishment is a directory |
price_level |
string | property price level can take values: inexpensive, moderate, expensive, very_expensiveif there is no price level information, the value will be null |
hotel_rating |
integer | hotel class rating class ratings range between 1-5 stars, learn more if there is no hotel class rating information, the value will be null |
| ‘Local Search Ad’ SERP element | ||
type |
string | type of element = ‘maps_paid_item’ |
rank_group |
integer | group rank in SERP position within a group of elements with identical type valuespositions of elements with different type values are omitted from rank_group |
rank_absolute |
integer | absolute rank in SERP absolute position among all the elements in SERP |
domain |
string | domain in the SERP element |
title |
string | title of the result in SERP |
url |
string | relevant URL in SERP |
contact_url |
string | URL of the preferred contact page |
rating |
object | the element’s rating the popularity rate based on reviews and displayed in SERP |
rating_type |
string | the type of rating here you can find the following elements: Max5, Percents, CustomMax |
value |
integer | the value of the rating |
votes_count |
integer | the amount of feedback |
rating_max |
integer | the maximum value for a rating_type |
rating_distribution |
object | the distribution of ratings of the business entity the object displays the number of 1-star to 5-star ratings, as reviewed by users |
1 |
integer | the number of 1-star ratings |
2 |
integer | the number of 2-star ratings |
3 |
integer | the number of 3-star ratings |
4 |
integer | the number of 4-star ratings | 5 |
integer | the number of 5-star ratings |