This endpoint will provide you with Google SERPs collected within the specified time frame. You will also receive a complete overview of featured snippets and other extra elements that were present within the specified dates. The data will allow you to analyze the dynamics of keyword rankings over time for the specified keyword and location.
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)"
curl --location --request POST "https://api.dataforseo.com/v3/dataforseo_labs/google/historical_serps/live"
--header "Authorization: Basic ${cred}"
--header "Content-Type: application/json"
--data-raw "[
{
"keyword": "albert einstein",
"location_code": 2840,
"language_code": "en",
"date_from": "2021-08-01",
"date_to": "2021-09-01"
}
]"
<?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');
$post_array = array();
// simple way to set a task
$post_array[] = array(
"keyword" => "albert einstein",
"location_code" => 2840,
"language_code" => "en",
"date_from" => "2021-08-01",
"date_to" => "2021-10-01"
);
try {
// POST /v3/dataforseo_labs/google/historical_serps/live
$result = $client->post('/v3/dataforseo_labs/google/historical_serps/live', $post_array);
print_r($result);
// do something with post 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;
?>
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")
post_data = dict()
# simple way to set a task
post_data[len(post_data)] = dict(
keyword="albert einstein",
location_name="United States",
language_name="English",
date_from="2021-08-01",
date_to="2021-10-01"
)
# POST /v3/dataforseo_labs/google/historical_serps/live
response = client.post("/v3/dataforseo_labs/google/historical_serps/live", post_data)
# you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if response["status_code"] == 20000:
print(response)
# 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 dataforseo_labs_google_historical_serps_live()
{
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"))) }
};
var postData = new List<object>();
postData.Add(new
{
keyword = "albert einstein",
location_name = "United States",
language_name = "English",
date_from = "2021-08-01",
date_to = "2021-10-01"
});
// POST /v3/dataforseo_labs/google/historical_serps/live
// the full list of possible parameters is available in documentation
var taskPostResponse = await httpClient.PostAsync("/v3/dataforseo_labs/google/historical_serps/live", new StringContent(JsonConvert.SerializeObject(postData)));
var result = JsonConvert.DeserializeObject(await taskPostResponse.Content.ReadAsStringAsync());
// you can find the full list of the response codes here https://docs.dataforseo.com/v3/appendix/errors
if (result.status_code == 20000)
{
// do something with result
Console.WriteLine(result);
}
else
Console.WriteLine($"error. Code: {result.status_code} Message: {result.status_message}");
}
}
}
The above command returns JSON structured like this:
All POST data should be sent in the JSON format (UTF-8 encoding). When setting a task, you should send all task parameters in the task array of the generic POST array. You can send up to 2000 API calls per minute, each Live SERP API call can contain only one task. The maximum number of requests that can be sent simultaneously is limited to 30.
Below you will find a detailed description of the fields you can use for setting a task.
Description of the fields for setting a task:
Field name
Type
Description
keyword
string
keyword required field
you can specify up to 700 characters in the keyword field;
all %## will be decoded (plus character ‘+’ will be decoded to a space character);
if you need to use the “%” character for your keyword, please specify it as “%25”;
if you need to use the “+” character for your keyword, please specify it as “%2B”
date_from
string
starting date of the time range
optional field
if you don’t specify this field, the API will return all SERPs collected for 365 days starting from the current datetime value;
minimal possible value: 365 days from the current datetime value;
date format: "yyyy-mm-dd"
date_to
string
ending date of the time range
optional field
if you don’t specify this field, the today’s date will be used by default;
date format: "yyyy-mm-dd";
example: "2021-09-01"
location_name
string
full name of the location required field if you don’t specifylocation_code Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example: United Kingdom
location_code
integer
unique location identifier required field if you don’t specifylocation_name Note: it is required to specify either location_name or location_code
you can receive the list of available locations with their location_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
example: 2840
language_name
string
full name of the language
optional field
if you use this field, you don’t need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example: English
language_code
string
language code
optional field
if you use this field, you don’t need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example: en
tag
string
user-defined task identifier
optional field the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response
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
the array includes objects with SERPs for each month within the specified time frame
se_type
string
search engine type
keyword
string
keyword received in a POST array the keyword is returned with decoded %## (plus character ‘+’ 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 accurate results
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
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
indicates whether the element is a featured_snippet
is_malicious
boolean
indicates whether the element is marked as malicious
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
amp_version
boolean
Accelerated Mobile Pages
indicates whether an item has the Accelerated Mobile Page (AMP) version
rating
object
the item’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
float
the value of the rating
votes_count
integer
the amount of feedback
rating_max
integer
the maximum value for a rating_type
highlighted
array
words highlighted in bold within the results description
links
array
sitelinks
the links shown below some of Google’s search results
if there are none, equals null
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
about_this_result
object
contains information from the ‘About this result’ panel ‘About this result’ panel provides additional context about why Google returned this result for the given query;
this feature appears after clicking on the three dots next to most results
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
description of the website from Wikipedia or another additional context
source_url
string
URL to full information from the source
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
main_domain
string
primary domain name in SERP
relative_url
string
URL in SERP that does not specify the HTTPs protocol and domain name
etv
float
estimated traffic volume
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and search volume values of the returned keyword
learn more about how the metric is calculated in this help center article
impressions_etv
float
estimated traffic volume based on impressions
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and impressions values of the returned keyword
learn more about how the metric is calculated in this help center article
estimated_paid_traffic_cost
float
estimated cost of converting organic search traffic into paid
represents the estimated monthly cost of running ads for the returned keyword
the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search
learn more about how the metric is calculated in this help center article
rank_changes
array
changes in rankings
ranking changes of the SERP element compared to the preceding month; Note: the changes are calculated even if the preceding month is not included in a POST request
previous_rank_absolute
integer
previous absolute rank in SERP
indicates previous rank of the element in Google SERP;
if this element is new, the value will be null
is_new
boolean
element was previously present in SERP
if the value is true, previously collected SERP didn’t contain this element
is_up
boolean
rank of this element went up
if the value is true, position of the element in SERP is higher compared to the previous check
is_down
boolean
rank of this element went down
if the value is true, position of the element in SERP is lower compared to the previous check
backlinks_info
object
backlinks information for the ranked website
referring_domains
integer
number of referring domains
referring domains include subdomains that are counted as separate domains for this metric
referring_main_domains
integer
number of referring main domains
referring_pages
integer
number of pages pointing to the ranked website
dofollow
integer
number of dofollow links
backlinks
integer
total number of backlinks
the total number of backlinks, including dofollow and nofollow links
time_update
string
date and time when backlink data was updated
in the UTC format: “yyyy-mm-dd hh-mm-ss +00:00”;
example: 2019-11-15 12:57:46 +00:00
rank_info
object
page and domain rank information
page_rank
integer
page rank page_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm;
learn more about the metric and how it is calculated in this help center article
main_domain_rank
integer
main domain rank main_domain_rank is calculated based on the method for node ranking in a linked database – a principle used in the original Google PageRank algorithm
learn more about the metric and how it is calculated in this help center article
words highlighted in bold within the results description
extra
array
additional information about the result
ad_aclk
string
the identifier of the ad
description_rows
array
extended description
if there is none, equals null
links
array
sitelinks
the links shown below some of Google’s search results
if there are none, equals null
type
string
type of element = ‘ad_link_element‘
title
string
title of the link element
description
string
description of the results element in SERP
url
string
URL link
ad_aclk
string
the identifier of the ad
main_domain
string
primary domain name in SERP
relative_url
string
URL in SERP that does not specify the HTTPs protocol and domain name
etv
float
estimated traffic volume
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and search volume values of the returned keyword
learn more about how the metric is calculated in this help center article
impressions_etv
float
estimated traffic volume based on impressions
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and impressions values of the returned keyword
learn more about how the metric is calculated in this help center article
estimated_paid_traffic_cost
float
estimated cost of paid monthly search traffic
represents the estimated cost of paid monthly traffic based on etv and cpc values
learn more about how the metric is calculated in this help center article
rank_changes
array
changes in rankings
ranking changes of the SERP element compared to the preceding month; Note: the changes are calculated even if the preceding month is not included in a POST request
previous_rank_absolute
integer
previous absolute rank in SERP
indicates previous rank of the element in Google SERP;
if this element is new, the value will be null
is_new
boolean
element was previously present in SERP
if the value is true, previously collected SERP didn’t contain this element
is_up
boolean
rank of this element went up
if the value is true, position of the element in SERP is higher compared to the previous check
is_down
boolean
rank of this element went down
if the value is true, position of the element in SERP is lower compared to the previous check
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
the item’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
main_domain
string
primary domain name in SERP
relative_url
string
URL in SERP that does not specify the HTTPs protocol and domain name
etv
float
estimated traffic volume
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and search volume values of the returned keyword
learn more about how the metric is calculated in this help center article
impressions_etv
float
estimated traffic volume based on impressions
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and impressions values of the returned keyword
learn more about how the metric is calculated in this help center article
estimated_paid_traffic_cost
float
estimated cost of converting organic search traffic into paid
represents the estimated monthly cost of running ads for the returned keyword
the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search
learn more about how the metric is calculated in this help center article
rank_changes
array
changes in rankings
ranking changes of the SERP element compared to the preceding month; Note: the changes are calculated even if the preceding month is not included in a POST request
previous_rank_absolute
integer
previous absolute rank in SERP
indicates previous rank of the element in Google SERP;
if this element is new, the value will be null
is_new
boolean
element was previously present in SERP
if the value is true, previously collected SERP didn’t contain this element
is_up
boolean
rank of this element went up
if the value is true, position of the element in SERP is higher compared to the previous check
is_down
boolean
rank of this element went down
if the value is true, position of the element in SERP is lower compared to the previous check
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
additional items present in the element
if there are none, equals null
type
string
type of element = ‘knowledge_graph_images_item‘
rank_group
integer
group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop
rank_absolute
integer
absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop
rank_absolute
integer
absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop
position
string
the alignment of the element in SERP
can take the following values: left, right
type of element = ‘knowledge_graph_description_item‘
rank_group
integer
group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop
rank_absolute
integer
absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop
rank_absolute
integer
absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop
rank_absolute
integer
absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop
rank_absolute
integer
absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop
rank_absolute
integer
absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop
position
string
the alignment of the element in SERP
can take the following values: left, right
google defined data attribute ID
example: kc:/local:place qa
expanded_element
array
link of the element
type
string
type of element = ‘knowledge_graph_expanded_element‘
featured_title
string
title of a given element
url
string
source URL
domain
string
source domain
title
string
source title
snippet
string
text alongside the title
table
object
table element
table_element
string
name assigned to the table element
possible values: table_element
table_header
array
column names
table_content
array
the content of the table
one line of the table in this element of the array
type
string
type of element = ‘knowledge_graph_shopping_item‘
rank_group
integer
group rank in SERP
position within a group of elements with identical type values;
positions of elements with different type values are omitted from rank_group;
always equals 0 for desktop
rank_absolute
integer
absolute rank in SERP
absolute position among all the elements in SERP
always equals 0 for desktop
position
string
the alignment of the element in SERP
can take the following values: left, right
the content of the table
one line of the table in this element of the array
main_domain
string
primary domain name in SERP
relative_url
string
URL in SERP that does not specify the HTTPs protocol and domain name
etv
float
estimated traffic volume
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and search volume values of the returned keyword
learn more about how the metric is calculated in this help center article
impressions_etv
float
estimated traffic volume based on impressions
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and impression values of the returned keyword
learn more about how the metric is calculated in this help center article
estimated_paid_traffic_cost
float
estimated cost of converting organic search traffic into paid
represents the estimated monthly cost of running ads for the returned keyword
the metric is calculated as the product of organic etv and paid cpc values and indicates the cost of driving the estimated volume of monthly organic traffic through PPC advertising in Google Search
learn more about how the metric is calculated in this help center article
rank_changes
array
changes in rankings
ranking changes of the SERP element compared to the preceding month; Note: the changes are calculated even if the preceding month is not included in a POST request
previous_rank_absolute
integer
previous absolute rank in SERP
indicates previous rank of the element in Google SERP;
if this element is new, the value will be null
is_new
boolean
element was previously present in SERP
if the value is true, previously collected SERP didn’t contain this element
is_up
boolean
rank of this element went up
if the value is true, position of the element in SERP is higher compared to the previous check
is_down
boolean
rank of this element went down
if the value is true, position of the element in SERP is lower compared to the previous check
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
source of the element
indicates the source of information provided in the stocks_box element
snippet
string
snippet of the element
price
object
price quote featured on Google at the time when our API pulled the results
note that stock prices displayed in the stocks_box element may be delayed according to Google Finance disclaimer
current
float
current price
indicates the current price quote featured on Google at the time when our API pulled the results
regular
float
regular price
indicates the regular price quote featured on Google at the time when our API pulled the results
max_value
float
the maximum price
indicates the maximum price quote featured on Google at the time when our API pulled the results
currency
string
currency of the listed price
ISO code of the currency applied to the price
is_price_range
boolean
price is provided as a range
indicates whether a price is provided in a range
displayed_price
string
price string in the result
raw price string as provided in the result
url
string
relevant URL
domain
string
domain in SERP
table
object
results table
if there are none, equals null
table_header
array
column names
if there are none, equals null
table_content
array
the content of the table
additional information about the stock prices displayed below the graph
if there is none, equals null
graph
object
contains data provided in the graph of the element
items
array
data provided for the date and time when our API pulled the results
type
string
type of element = ‘graph_element’
corresponds to one point on the graph that indicates the stock price for a specific date and time
date
string
date and time
in the yyyy-mm-ddThh:mm:ssISO 8601 format
indicates date and time for which the stock price in the value field is provided
value
float
stock price
stock price for the date and time provided in the date field
previous_items
array
previous close data
contains stock price data based on the preceding time period
type
string
type of element = ‘graph_element’
corresponds to one point on the graph that indicates the stock price for a specific date and time
date
string
date and time
in the yyyy-mm-ddThh:mm:ssISO 8601 format
indicates the date and time for which the value field provides previous close price
for example, "date": "2020-10-28T15:45:00" and "value": 11080.2857 mean the stock was traded at 11080.2857 on Oct. 27, 2020 at 15:45:00
value
float
previous close price
closing price on the preceding time period
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
items
array
contains results featured in the visual_stories element of SERP
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
items
array
contains results featured in the commercial_units element of SERP
type
string
type of element = ‘commercial_units_element’
title
string
title of the commercial unit
url
string
relevant URL
domain
string
domain in SERP
price
object
price indicated in the element
current
float
current price
indicates the current price of the commercial units element
regular
float
regular price
indicates the regular price of the commercial units element
max_value
float
the maximum price
indicates the maximum price of the commercial units element
currency
string
currency of the listed price
ISO code of the currency applied to the price
is_price_range
boolean
price is provided as a range
indicates whether a price is provided in a range
displayed_price
string
price string in the result
raw price string as provided in the result
source
string
source of the element
rating
object
the item’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
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
domain
string
domain in SERP
items
array
contains results featured in the local_services element of SERP
type
string
type of element = ‘local_services_element’
title
string
title of the local services element
url
string
relevant URL
domain
string
domain in SERP
description
string
description of the local services element
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
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right
group rank in SERP
position within a group of elements with identical type values
positions 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
position
string
the alignment of the element in SERP
can take the following values: left, right