Serp
Live SERP provides real-time data on search engine results for the specified keyword, search engine, and location.
post/v3/serp/bing/organic/live/regular
Request
- Base URL: https://api.dataforseo.com
- URL: https://api.dataforseo.com/v3/serp/bing/organic/live/regular
- Auth: HTTP basic
Request body
keywordstring
<p><em>keyword</em><p><strong>required field</strong><p>you can specify <strong>up to 700 characters</strong> in the <code>keyword</code> field<p><strong>all %## will be decoded (plus character '+' will be decoded to a space character)</strong><p>if you need to use the "%" character for your <code>keyword</code>, please specify it as "%25";<p>if you need to use the “+” character for your <code>keyword</code>, please specify it as “%2B”;</p><br><p>learn more about rules and limitations of <code>keyword</code> and <code>keywords</code> fields in DataForSEO APIs in this <a href="https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis" rel="noopener noreferrer" target="_blank">Help Center article</a></p>
location_codeinteger
<p><em>search engine location code</em><p><strong>required field if you don't specify</strong> <code>location_name</code> or <code>location_coordinate</code><p><strong>if you use this field, you don't need to specify <code>location_name</code> or <code>location_coordinate</code></strong><p>you can receive the list of available locations of the search engines with their <code>location_code</code> by making a separate request to the <code>https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations</code><p>example:<p><code class="long-string">2840</code></p>
language_codestring
<p><em>search engine language code</em><p><strong>required field if you don't specify</strong> <code>language_name</code><p><strong>if you use this field, you don't need to specify <code>language_name</code></strong><p>you can receive the list of available languages of the search engine with their <code>language_code</code> by making a separate request to the <code>https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages</code><em><p></em>example:<em><p></em><code class="long-string">en</code></p>
depthinteger nullable
<p><em>parsing depth</em><p>optional field<p>number of results in SERP<p>default value: <code>10</code><p>max value: <code>200</code></p><br><strong>Your account will be billed per each SERP containing up to 10 results;</strong><p>Setting depth above 10 may result in additional charges <a href="https://dataforseo.com/help-center/how-many-results-scraped" rel="noopener noreferrer" target="_blank">if the search engine returns more than 10 results</a>;<p>The cost can be calculated on the <a title="Pricing" href="https://dataforseo.com/pricing/serp/bing-organic-serp-api" target="_blank" rel="noopener noreferrer">Pricing</a> page.
devicestring nullable
<p><em>device type</em><p>optional field<p>return results for a specific device type<p>can take the values:<code>desktop</code>, <code>mobile</code><p>default value: <code>desktop</code></p>
location_namestring
<p><em>full name of search engine location</em><p><strong>required field if you don't specify</strong> <code>location_code</code> or <code>location_coordinate</code><p><strong>if you use this field, you don't need to specify <code>location_code</code> or <code>location_coordinate</code></strong><p>you can receive the list of available locations of the search engine with their <code>location_name</code> by making a separate request to the <code>https://api.dataforseo.com/v3/serp/{{low_se_name}}/locations</code><p>example:<p><code class="long-string">London,England,United Kingdom</code></p>
language_namestring
<p><em>full name of search engine language</em><p><strong>required field if you don't specify</strong> <code>language_code</code><p><strong>if you use this field, you don't need to specify <code>language_code</code></strong><p>you can receive the list of available languages of the search engine with their <code>language_name</code> by making a separate request to the <code>https://api.dataforseo.com/v3/serp/{{low_se_name}}/languages</code><p>example:<p><code class="long-string">English</code></p>
osstring nullable
<p><em>device operating system</em><p>optional field<p>if you specify <code>desktop</code> in the <code>device</code> field, choose from the following values: <code>windows</code>, <code>macos</code><p>default value: <code>windows</code><p>if you specify <code>mobile</code> in the <code>device</code> field, choose from the following values: <code>android</code>, <code>ios</code><p>default value: <code>android</code></p>
tagstring nullable
<p><em>user-defined task identifier</em><p>optional field<p><em>the character limit is 255</em><p>you can use this parameter to identify the task and match it with the result<p>you will find the specified <code>tag</code> value in the <code>data</code> object of the response</p>
targetstring nullable
<p><em>target domain, subdomain, or webpage to get results for</em><p>optional field<p>a domain or a subdomain should be specified without <code>https://</code> and <code>www.</code><p>note that the results of <code>target</code>-specific tasks will only include SERP elements that contain a <code>url</code> string;<p>you can also use a wildcard (‘*’) character to specify the search pattern in SERP and narrow down the results;<p>examples:<p><strong><code class="long-string">example.com</code></strong> - returns results for the website's home page with URLs, such as <code class="long-string">https://example.com</code>, or <code class="long-string">https://www.example.com/</code>, or <code class="long-string">https://example.com/</code>;<p><strong><code class="long-string">example.com*</code></strong> - returns results for the domain, including all its pages;<p><strong><code class="long-string">*example.com*</code></strong> - returns results for the entire domain, including all its pages and subdomains;<p><strong><code class="long-string">*example.com</code></strong> - returns results for the home page regardless of the subdomain, such as <code class="long-string">https://en.example.com</code>;<p><strong><code class="long-string">example.com/example-page</code></strong> - returns results for the exact URL;<p><strong><code class="long-string">example.com/example-page*</code></strong> - returns results for all domain's URLs that start with the specified string</p>
match_typestring
<p><em>target match type</em><p><strong>required field if <code>stop_crawl_on_match</code> is specified</strong><p>type of match for the <code>match_value</code><p>possible values:<p><code>domain</code> – specific domain or subdomain<p><code>with_subdomains</code> – main domain and subdomains<p><code>wildcard</code> – wildcard pattern</p>
match_valuestring
<p><em>target domain, subdomain, or wildcard value</em><p><strong>required field if <code>stop_crawl_on_match</code> is specified</strong><p>specify a target domain, subdomain, or wildcard value;<p><strong>Note:</strong> domain or subdomain must be specified without a request protocol;<p>example: <code>"match_value": "dataforseo.com"</code>,<p><code>"match_value": "/blog/post-*"</code></p>
max_crawl_pagesinteger nullable
<p><em>page crawl limit</em><p>optional field<p>number of search results pages to crawl<p>default value: <code>1</code><p>max value: <code>100</code><p><strong>Note:</strong> the <code>max_crawl_pages</code> and <code>depth</code> parameters complement each other;<p>learn more at <a href="https://dataforseo.com/help-center/what-is-max-crawl-pages-and-how-does-it-work" rel="noopener noreferrer" target="_blank">our help center</a></p>
search_paramstring nullable
<p><em>additional parameters of the search query</em><p>optional field<p><a href="https://dataforseo.com/what-are-google-search-parameters-and-how-to-use-them-with-serp-api.html">get the list of available parameters and additional details here</a></p>
urlstring nullable
<p><em>direct URL of the search query</em><p>optional field<p>you can specify a direct URL and we will sort it out to the necessary fields. Note that this method is the most difficult for our API to process and also requires you to specify the exact language and location in the URL. In most cases, we wouldn’t recommend using this method.<p>example:<p><code class="long-string">https://www.bing.com/search?q=rank%20checker&count=50&first=1&setlang=en&cc=US&safesearch=Moderate&FORM=SEPAGE</code></p>
location_coordinatestring
<p><em>GPS coordinates of a location</em><p><strong>required field if you don't specify</strong> <code>location_name</code> or <code>location_code</code><p><strong>if you use this field, you don't need to specify <code>location_name</code> or <code>location_code</code></strong><p><code>location_coordinate</code> parameter should be specified in the <em>"latitude,longitude"</em> format<p>the maximum number of decimal digits for <em>"latitude"</em> and <em>"longitude"</em>: 7<p>example:<p><code class="long-string">53.476225,-2.243572</code></p>
Example request
[
{
"language_code": "en",
"location_code": 2840,
"keyword": "albert einstein"
}
]Response
Successful operation
versionstring nullable
the current version of the API
status_codeinteger nullable
general status code you can find the full list of the response codes here
status_messagestring nullable
general informational message you can find the full list of general informational messages here
timestring nullable
total execution time, seconds
costnumber double nullable
total tasks cost, USD
tasks_countinteger nullable
the number of tasks in the tasks array
tasks_errorinteger nullable
the number of tasks in the tasks array returned with an error
Changes
- breaking
the request property
/////became not nullable - breaking
the request property
/////became not nullable - breaking
the request property
/////became not nullable - breaking
the request property
/////became not nullable - breaking
the request property
/////became not nullable - breaking
the request property
/////became not nullable - breaking
the request property
/////became not nullable
- breaking
- breaking
added to the
//////////////////////////////response propertyoneOflist for the response status - info
removed from the
//////////////////////////////response propertyoneOflist for the response status
- breaking