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_expensive if 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 |