Your account will be charged only for posting a task. You can get the results of the task within the next 30 days for free.
The cost can be calculated on the Pricing page.
Description of the fields for sending a request:
| Field name | Type | Description |
|---|---|---|
id | string | task identifier |
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.
You can also get all available SERP features and possible extra elements by making a request to the following Sandbox URL:
https://sandbox.dataforseo.com/v3/serp/google/search_by_image/task_get/advanced/00000000-0000-0000-0000-000000000000
The response will include all available items in the Google Search by Image SERP Advanced endpoint with the fields containing dummy data.
You won’t be charged for using Sandbox endpoints.
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 |
status_message | string | general informational message |
time | string | execution time, seconds |
cost | float | total tasks cost, USD |
tasks_count | integer | the number of tasks in the |
tasks_error | integer | the number of tasks in the |
tasks | array | array of tasks |
id | string | task identifier |
status_code | integer | status code of the task |
status_message | string | informational message of the task |
time | string | execution time, seconds |
cost | float | cost of the task, USD |
result_count | integer | number of elements in the |
path | array | URL path |
data | object | contains the same parameters that you specified in the POST request |
result | array | array of results |
image_url | string | URL specified in a POST array |
keyword | string | keyword Google associated with the specified image |
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 |
datetime | string | date and time when the result was received |
spell | object | autocorrection of the search engine |
keyword | string | keyword obtained as a result of search engine autocorrection |
type | string | type of autocorrection |
refinement_chips | object | search refinement chips |
type | string | type of element = 'refinement_chips' |
xpath | string | the XPath of the element |
items | array | items of the element |
type | string | type of element = 'refinement_chips_element' |
title | string | title of the element |
url | string | search URL with refinement parameters |
domain | string | domain in SERP |
options | array | further search refinement options |
type | string | type of element = 'refinement_chips_option' |
title | string | title of the element |
url | string | search URL with refinement parameters |
domain | string | domain in SERP |
item_types | array | types of search results in SERP |
se_results_count | integer | total number of results in SERP |
items_count | integer | the number of results returned in the |
items | array | elements of search results found in SERP |
organic | object | |
type | string | type of element = 'organic' |
rank_group | integer | group rank in SERP |
rank_absolute | integer | absolute rank in SERP |
position | string | the alignment of the element in SERP |
xpath | string | the XPath of the element |
domain | string | domain in SERP |
title | string | title of the result in SERP |
url | string | relevant URL in SERP |
cache_url | string | cached version of the page |
related_search_url | string | URL to a similar search |
breadcrumb | string | breadcrumb in SERP |
website_name | string | name of the website in SERP |
is_image | boolean | indicates whether the element contains an |
is_video | boolean | indicates whether the element contains a |
is_featured_snippet | boolean | indicates whether the element is a |
is_malicious | boolean | indicates whether the element is marked as malicious |
is_web_story | boolean | indicates whether the element is marked as Google web story |
description | string | description of the results element in SERP |
pre_snippet | string | includes additional information appended before the result description in SERP |
extended_snippet | string | includes additional information appended after the result description in SERP |
images | array | images of the element |
type | string | type of element = 'images_element' |
alt | string | alt tag of the image |
url | string | relevant URL |
image_url | string | URL of the image |
amp_version | boolean | Accelerated Mobile Pages |
rating | object | the item's rating |
rating_type | string | the type of rating |
value | float | the value of the rating |
votes_count | integer | the amount of feedback |
rating_max | integer | the maximum value for a |
price | object | pricing details |
current | float | current price |
regular | float | regular price |
max_value | float | the maximum price |
currency | string | currency of the listed price |
is_price_range | boolean | price is provided as a range |
displayed_price | string | price string in the result |
highlighted | array | words highlighted in bold within the results |
links | array | sitelinks |
type | string | type of element = 'link_element' |
title | string | title of the result in SERP |
description | string | description of the results element in SERP |
url | string | sitelink URL |
domain | string | domain in SERP |
faq | object | frequently asked questions |
type | string | type of element = 'faq_box' |
items | array | items featured in the faq_box |
type | string | type of element = 'faq_box_element' |
title | string | question related to the result |
description | string | answer provided in the drop-down block |
links | array | links featured in the faq_box_element |
type | string | type of element = 'link_element' |
title | string | link anchor text |
url | string | link URL |
domain | string | domain in SERP |
extended_people_also_search | array | extension of the organic element |
about_this_result | object | contains information from the 'About this result' panel |
type | string | type of element = 'about_this_result_element' |
url | string | result's URL |
source | string | source of additional information about the result |
source_info | string | additional information about the result |
source_url | string | URL to full information from the |
language | string | the language of the result |
location | string | location for which the result is relevant |
search_terms | array | matching search terms that appear in the result |
related_terms | array | related search terms that appear in the result |
related_result | array | related result from the same domain |
type | string | type of element = 'related_result' |
xpath | string | the XPath of the element |
domain | string | relevant domain |
title | string | title of the result in SERP |
url | string | relevant URL in SERP |
cache_url | string | cached version of the page |
related_search_url | string | URL to a similar search |
breadcrumb | string | breadcrumb in SERP |
is_image | boolean | indicates whether the element contains an |
is_video | boolean | indicates whether the element contains a |
description | string | description of the results element in SERP |
pre_snippet | string | includes additional information appended before the result description in SERP |
extended_snippet | string | includes additional information appended after the result description in SERP |
images | array | images of the element |
type | string | type of element = 'images_element' |
alt | string | alt tag of the image |
url | string | relevant URL |
image_url | string | URL of the image |
amp_version | boolean | Accelerated Mobile Pages |
rating | object | the item's rating |
rating_type | string | the type of rating |
value | float | the value of the rating |
votes_count | integer | the amount of feedback |
rating_max | integer | the maximum value for a |
price | object | pricing details |
current | float | current price |
regular | float | regular price |
max_value | float | the maximum price |
currency | string | currency of the listed price |
is_price_range | boolean | price is provided as a range |
displayed_price | string | price string in the result |
highlighted | array | words highlighted in bold within the results |
about_this_result | object | contains information from the 'About this result' panel |
type | string | type of element = 'about_this_result_element' |
url | string | result's URL |
source | string | source of additional information about the result |
source_info | string | additional information about the result |
source_url | string | URL to full information from the |
language | string | the language of the result |
location | string | location for which the result is relevant |
search_terms | array | matching search terms that appear in the result |
related_terms | array | related search terms that appear in the result |
timestamp | string | date and time when the result was published |
timestamp | string | date and time when the result was published |
rectangle | object | rectangle parameters |
x | integer | x-axis coordinate |
y | integer | y-axis coordinate |
width | integer | width of the element in pixels |
height | integer | height of the element in pixels |
images | object | |
type | string | type of element = 'images' |
rank_group | integer | group rank in SERP |
rank_absolute | integer | absolute rank in SERP |
position | string | the alignment of the element in SERP |
xpath | string | the XPath of the element |
title | string | title of the result in SERP |
url | string | relevant URL |
items | array | additional items present in the element |
type | string | type of element = 'images_element' |
alt | string | alt tag of the image |
url | string | URL of the image resource |
image_url | string | URL to the compressed image |
related_image_searches | array | contains keywords and images related to the specified search term |
type | string | type of element = 'related_image_searches_element' |
title | string | title of the element |
alt | string | alt tag of the featured image |
url | string | original URL of the featured image |
image_url | string | URL to the compressed featured image |
rectangle | object | rectangle parameters |
x | integer | x-axis coordinate |
y | integer | y-axis coordinate |
width | integer | width of the element in pixels |
height | integer | height of the element in pixels |
Instead of ‘login’ and ‘password’ use your credentials from https://app.dataforseo.com/api-access
# Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
login="login"
password="password"
cred="$(printf ${login}:${password} | base64)"
id="02261816-2027-0066-0000-c27d02864073"
curl --location --request GET "https://api.dataforseo.com/v3/serp/google/search_by_image/task_get/advanced/${id}"
--header "Authorization: Basic ${cred}"
--header "Content-Type: application/json"
--data-raw ""<?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/';
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
$client = new RestClient($api_url, null, 'login', 'password');
try {
$result = array();
// #1 - using this method you can get a list of completed tasks
// GET /v3/serp/google/search_by_image/tasks_ready
// in addition to 'google' and 'search_by_image' 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/google/search_by_image/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/google/search_by_image/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/google/search_by_image/task_get/advanced/$id
/*
if (isset($task_ready['id'])) {
$result[] = $client->get('/v3/serp/google/search_by_image/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;
?>const task_id = '02231934-2604-0066-2000-570459f04879';
const axios = require('axios');
axios({
method: 'get',
url: 'https://api.dataforseo.com/v3/serp/google/search_by_image/task_get/advanced/' + task_id,
auth: {
username: 'login',
password: 'password'
},
headers: {
'content-type': 'application/json'
}
}).then(function (response) {
var result = response['data']['tasks'];
// Result data
console.log(result);
}).catch(function (error) {
console.log(error);
});from client import RestClient
# You can download this file from here https://cdn.dataforseo.com/v3/examples/python/python_Client.zip
client = RestClient("login", "password")
# 1 - using this method you can get a list of completed tasks
# GET /v3/serp/google/search_by_image/tasks_ready
# in addition to 'google' and 'search_by_image' you can also set other search engine and type parameters
# the full list of possible parameters is available in documentation
response = client.get("/v3/serp/google/search_by_image/tasks_ready")
# you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if response['status_code'] == 20000:
results = []
for task in response['tasks']:
if (task['result'] and (len(task['result']) > 0)):
for resultTaskInfo in task['result']:
# 2 - using this method you can get results of each completed task
# GET /v3/serp/google/search_by_image/advanced/$id
if(resultTaskInfo['endpoint_advanced']):
results.append(client.get(resultTaskInfo['endpoint_advanced']))
'''
# 3 - another way to get the task results by id
# GET /v3/serp/google/search_by_image/task_get/advanced/$id
if(resultTaskInfo['id']):
results.append(client.get("/v3/serp/google/search_by_image/task_get/advanced/" + resultTaskInfo['id']))
'''
print(results)
# do something with result
else:
print("error. Code: %d Message: %s" % (response["status_code"], response["status_message"]))using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
namespace DataForSeoDemos
{
public static partial class Demos
{
public static async Task serp_task_get()
{
var httpClient = new HttpClient
{
BaseAddress = new Uri("https://api.dataforseo.com/"),
// Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
DefaultRequestHeaders = { Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes("login:password"))) }
};
// #1 - using this method you can get a list of completed tasks
// GET /v3/serp/google/search_by_image/tasks_ready
// in addition to 'google' and 'search_by_image' you can also set other search engine and type parameters
// the full list of possible parameters is available in documentation
var response = await httpClient.GetAsync("/v3/serp/google/search_by_image/tasks_ready");
var tasksInfo = JsonConvert.DeserializeObject(await response.Content.ReadAsStringAsync());
var tasksResponses = new List<object>();
// you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if (tasksInfo.status_code == 20000)
{
if (tasksInfo.tasks != null)
{
foreach (var tasks in tasksInfo.tasks)
{
if (tasks.result != null)
{
foreach (var task in tasks.result)
{
if (task.endpoint_advanced != null)
{
// #2 - using this method you can get results of each completed task
// GET /v3/serp/google/search_by_image/task_get/advanced/$id
var taskGetResponse = await httpClient.GetAsync((string)task.endpoint_advanced);
var taskResultObj = JsonConvert.DeserializeObject(await taskGetResponse.Content.ReadAsStringAsync());
if (taskResultObj.tasks != null)
{
var fst = taskResultObj.tasks.First;
// you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if (fst.status_code >= 40000 || fst.result == null)
Console.WriteLine($"error. Code: {fst.status_code} Message: {fst.status_message}");
else
tasksResponses.Add(fst.result);
}
// #3 - another way to get the task results by id
// GET /v3/serp/google/search_by_image/task_get/advanced/$id
/*
var tasksGetResponse = await httpClient.GetAsync("/v3/serp/google/search_by_image/task_get/advanced/" + (string)task.id);
var tasksResultObj = JsonConvert.DeserializeObject(await tasksGetResponse.Content.ReadAsStringAsync());
if (tasksResultObj.tasks != null)
{
var fst = taskResultObj.tasks.First;
// you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if (fst.status_code >= 40000 || fst.result == null)
Console.WriteLine($"error. Code: {fst.status_code} Message: {fst.status_message}");
else
tasksResponses.Add(fst.result);
}
*/
}
}
}
}
}
if (tasksResponses.Count > 0)
// do something with result
Console.WriteLine(String.Join(Environment.NewLine, tasksResponses));
else
Console.WriteLine("No completed tasks");
}
else
Console.WriteLine($"error. Code: {tasksInfo.status_code} Message: {tasksInfo.status_message}");
}
}
}The above command returns JSON structured like this:
{
"version": "0.1.20230825",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0957 sec.",
"cost": 0,
"tasks_count": 1,
"tasks_error": 0,
"tasks": [
{
"id": "11151921-1535-0066-0000-2c32bed229f2",
"status_code": 20000,
"status_message": "Ok.",
"time": "0.0280 sec.",
"cost": 0,
"result_count": 1,
"path": [
"v3",
"serp",
"google",
"search_by_image",
"task_get",
"advanced",
"11151921-1535-0066-0000-2c32bed229f2"
],
"data": {
"api": "serp",
"function": "task_get",
"se": "google",
"se_type": "search_by_image",
"language_code": "en",
"location_code": 2840,
"image_url": "https://www.shutterstock.com/blog/wp-content/uploads/sites/5/2021/11/shutterstock_721703848.jpg?w=580&h=580&crop=1",
"priority": 2,
"device": "desktop",
"os": "windows"
},
"result": [
{
"image_url": "https://www.shutterstock.com/blog/wp-content/uploads/sites/5/2021/11/shutterstock_721703848.jpg?w=580&h=580&crop=1",
"keyword": null,
"type": "search_by_image",
"se_domain": "lens.google.com",
"location_code": 2840,
"language_code": "en",
"check_url": "https://lens.google.com/uploadbyurl?url=https%3A%2F%2Fwww.shutterstock.com%2Fblog%2Fwp-content%2Fuploads%2Fsites%2F5%2F2021%2F11%2Fshutterstock_721703848.jpg%3Fw%3D580%26h%3D580%26crop%3D1&hl=en&gl=US&ie=UTF-8&oe=UTF-8&uule=w+CAIQIFISCQs2MuSEtepUEUK33kOSuTsc&ep=gisbubu",
"datetime": "2023-11-15 17:21:31 +00:00",
"spell": null,
"refinement_chips": null,
"item_types": [
"images",
"organic"
],
"se_results_count": 0,
"items_count": 61,
"items": [
{
"type": "images",
"rank_group": 1,
"rank_absolute": 1,
"position": "left",
"xpath": null,
"title": "Marmalade Art Tropical Flower Wallpaper Mural",
"url": null,
"items": [
{
"type": "images_element",
"alt": "Image #1 for Marmalade Art Tropical Flower Wallpaper Mural",
"url": "https://www.mural-wallpaper.com/product/wallpaper-murals/nature/flowers-plants/tropical-flower-wallpaper-mural/",
"image_url": "https://t2.gstatic.com/images?q=tbn:ANd9GcS0tPJeCrLWv2Dm5C2x32EGaYKv39ciGV-bzKfU_-8mdpTLZdrS"
},
{
"type": "images_element",
"alt": "Image #2 for Marmalade Art Tropical Flower Wallpaper Mural",
"url": "https://www.mural-wallpaper.com/product/wallpaper-murals/nature/flowers-plants/tropical-flower-wallpaper-mural/",
"image_url": "https://t2.gstatic.com/images?q=tbn:ANd9GcRi0yMpTv31JTW92ZhX89CWE2GsB3XMktAiKeaBhW20YyhM20uU"
},
{
"type": "images_element",
"alt": "Image #3 for Marmalade Art Tropical Flower Wallpaper Mural",
"url": "https://www.mural-wallpaper.com/product/wallpaper-murals/art-design/modern/tropical-flora-wall-art/",
"image_url": "https://t1.gstatic.com/images?q=tbn:ANd9GcQ_ckV6piXQuE7yR1c2lsEdSEEAad6u0rKgBc92_pvoPATYODab"
}
],
"related_image_searches": null,
"rectangle": null
},
{
"type": "organic",
"rank_group": 1,
"rank_absolute": 2,
"position": "left",
"xpath": null,
"domain": "$43.35* • Amazon",
"title": "ART.COM Wall Art Prints Colorful Flower on Dark Tropical Foliage Nature Background, Botanical Decor, 36" x 24"",
"url": "https://www.amazon.com/ART-COM-Colorful-Tropical-Background-Botanical/dp/B0CBL4YQ1L",
"cache_url": null,
"related_search_url": null,
"breadcrumb": null,
"website_name": null,
"is_image": true,
"is_video": false,
"is_featured_snippet": false,
"is_malicious": false,
"is_web_story": false,
"description": null,
"pre_snippet": null,
"extended_snippet": null,
"images": [
{
"type": "images_element",
"alt": null,
"url": "https://www.amazon.com/ART-COM-Colorful-Tropical-Background-Botanical/dp/B0CBL4YQ1L",
"image_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTMeZt2_Qd0aOrJnJR801KKaE7mVjC5T2VpH1wdbcfHhfB3PU3l"
}
],
"amp_version": false,
"rating": null,
"price": null,
"highlighted": null,
"links": null,
"faq": null,
"extended_people_also_search": null,
"about_this_result": null,
"related_result": null,
"timestamp": null,
"rectangle": null
},
{
"type": "organic",
"rank_group": 2,
"rank_absolute": 3,
"position": "left",
"xpath": null,
"domain": "twitter.com",
"title": "everpix on X: "Today is a good day to change the #wallpaper 👌🏻😏😍 #wallpapers #iphonewallpapers #iphonewallpaper #background #backgrounds #bestbackground #bestwallpaper #iphone_wallpaper #iphone_wallpapers #everpix #everpixlive #livewallpaper #contrast #abstractart #abstarct #brightbackground https://t.co/4XYPcKED2G" / X",
"url": "https://twitter.com/everpixapp/status/1097804893534982144",
"cache_url": null,
"related_search_url": null,
"breadcrumb": null,
"website_name": null,
"is_image": true,
"is_video": false,
"is_featured_snippet": false,
"is_malicious": false,
"is_web_story": false,
"description": null,
"pre_snippet": null,
"extended_snippet": null,
"images": [
{
"type": "images_element",
"alt": null,
"url": "https://twitter.com/everpixapp/status/1097804893534982144",
"image_url": "https://encrypted-tbn2.gstatic.com/images?q=tbn:ANd9GcTOVoJ5uKZZC4TrvK1B9Xr06SdnxZWc8gwTCS4h8Kn7VGC9g6Zs"
}
],
"amp_version": false,
"rating": null,
"price": null,
"highlighted": null,
"links": null,
"faq": null,
"extended_people_also_search": null,
"about_this_result": null,
"related_result": null,
"timestamp": null,
"rectangle": null
},
{
"type": "organic",
"rank_group": 3,
"rank_absolute": 4,
"position": "left",
"xpath": null,
"domain": "$10.82* • Redbubble",
"title": "Golden Tropical Bloom + Blue-Green Jungle Leaves Art Board Print",
"url": "https://www.redbubble.com/i/art-board-print/Golden-Tropical-Bloom-Blue-Green-Jungle-Leaves-by-EscapistDecor/64463975.5E8EA",
"cache_url": null,
"related_search_url": null,
"breadcrumb": null,
"website_name": null,
"is_image": true,
"is_video": false,
"is_featured_snippet": false,
"is_malicious": false,
"is_web_story": false,
"description": null,
"pre_snippet": null,
"extended_snippet": null,
"images": [
{
"type": "images_element",
"alt": null,
"url": "https://www.redbubble.com/i/art-board-print/Golden-Tropical-Bloom-Blue-Green-Jungle-Leaves-by-EscapistDecor/64463975.5E8EA",
"image_url": "https://encrypted-tbn2.gstatic.com/images?q=tbn:ANd9GcTZbQrafPWoRqWZ9On0nVXTPlzUpCjyqA5-RliIbwjszGnqBMVN"
}
],
"amp_version": false,
"rating": null,
"price": null,
"highlighted": null,
"links": null,
"faq": null,
"extended_people_also_search": null,
"about_this_result": null,
"related_result": null,
"timestamp": null,
"rectangle": null
},
{
"type": "organic",
"rank_group": 4,
"rank_absolute": 5,
"position": "left",
"xpath": null,
"domain": "globalgovernanceproject.org",
"title": "Inger Andersen, Author at The Global Governance Project",
"url": "https://www.globalgovernanceproject.org/author/inger-andersen/",
"cache_url": null,
"related_search_url": null,
"breadcrumb": null,
"website_name": null,
"is_image": true,
"is_video": false,
"is_featured_snippet": false,
"is_malicious": false,
"is_web_story": false,
"description": null,
"pre_snippet": null,
"extended_snippet": null,
"images": [
{
"type": "images_element",
"alt": null,
"url": "https://www.globalgovernanceproject.org/author/inger-andersen/",
"image_url": "https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcSLR7aWtbhOdJQbYqQ4aBLEFd_0EH6_iR1_axJTXqSzgW74jcnC"
}
],
"amp_version": false,
"rating": null,
"price": null,
"highlighted": null,
"links": null,
"faq": null,
"extended_people_also_search": null,
"about_this_result": null,
"related_result": null,
"timestamp": null,
"rectangle": null
}
]
}
]
}
]
}