Sign in
Serp

Changed on

‌‌ Google AI Mode SERP API provides search results from the AI Mode feature of Google Search.

post/v3/serp/google/ai_mode/live/advanced

Request

  • Base URL: https://api.dataforseo.com
  • URL: https://api.dataforseo.com/v3/serp/google/ai_mode/live/advanced
  • 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>all %## will be decoded (plus character ‘+’ will be decoded to a space character)<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>&nbsp;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/google/locations</code><p><strong>Note:</strong> check <a href="https://support.google.com/websearch/answer/16011537?hl=en&amp;co=GENIE.Platform%3DAndroid#" target="_blank"> Google Search Help</a> for the list of countries where AI Mode is currently available</p>
language_codestring
<p><em>search engine language code</em><p>required field if you don't specify <code>language_name</code>;<p>if you use this field, you don't need to specify <code>language_name</code>;<p>you can receive the list of available languages of the search engine with their <code>language_code</code>&nbsp;by making a separate request to the <code>https://api.dataforseo.com/v3/serp/google/ai_mode/languages</code></p>
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/google/locations</code><p><strong>Note:</strong> check <a href="https://support.google.com/websearch/answer/16011537?hl=en&amp;co=GENIE.Platform%3DAndroid#" target="_blank"> Google Search Help</a> for the list of countries where AI Mode is currently available</p>
language_namestring
<p><em>full name of search engine language</em><p>required field if you don't specify <code>language_code</code>;<p>if you use this field, you don't need to specify <code>language_code</code>;<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/google/ai_mode/languages</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>
calculate_rectanglesboolean nullable
<p><em>calculate pixel rankings for SERP elements in advanced results</em><p>optional field<p>pixel ranking refers to the distance between the result snippet and top left corner of the screen;<p><a href="https://dataforseo.com/help-center/pixel-ranking-in-serp-api">Visit Help Center to learn more&gt;&gt;</a><p>by default, the parameter is set to <code>false</code><p><strong>Note:</strong> if set to <code>true</code>, the charge per task will be multiplied by 2</p>
browser_screen_widthinteger nullable
<p><em>browser screen width</em><p>optional field<p>you can set a custom browser screen width to calculate pixel rankings for a particular device;<p>can be specified within the following range: <code>240-9999</code>;<p>by default, the parameter is set to:<p><code>1920</code> for <code>desktop</code>;<p><code>360</code> for <code>mobile</code> on <code>android</code>;<p><code>375</code> for <code>mobile</code> on <code>iOS</code>;<p><strong>Note:</strong> to use this parameter, set <code>calculate_rectangles</code> to <code>true</code></p>
browser_screen_heightinteger nullable
<p><em>browser screen height</em><p>optional field<p>you can set a custom browser screen height to calculate pixel rankings for a particular device;<p>can be specified within the following range: <code>240-9999</code>;<p>by default, the parameter is set to:<p><code>1080</code> for <code>desktop</code>;<p><code>640</code> for <code>mobile</code> on <code>android</code>;<p><code>812</code> for <code>mobile</code> on <code>iOS</code>;<p><strong>Note:</strong> to use this parameter, set <code>calculate_rectangles</code> to <code>true</code></p>
browser_screen_resolution_ratiointeger nullable
<p><em>browser screen resolution ratio</em><p>optional field<p>you can set a custom browser screen resolution ratio to calculate pixel rankings for a particular device;<p>can be specified within the following range: <code>0.5-3</code>;<p>by default, the parameter is set to:<p><code>1</code> for <code>desktop</code>;<p><code>3</code> for <code>mobile</code> on <code>android</code>;<p><code>3</code> for <code>mobile</code> on <code>iOS</code>;<p><strong>Note:</strong> to use this parameter, set <code>calculate_rectangles</code> to <code>true</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>&nbsp;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,zoom"</em> format<p>if <em>"zoom"</em> is not specified, <em>9z</em> will be applied as a default value<p>the maximum number of decimal digits for <em>"latitude"</em> and <em>"longitude"</em>: 7<p>the minimum value for <em>"zoom"</em>: 4z<p>the maximum value for <em>"zoom"</em>: 18z<p>example:<p><code class="long-string">52.6178549,-155.352142,18z</code></p>

Example request

[
  {
    "language_code": "en",
    "location_code": 2840,
    "keyword": "what is google ai mode"
  }
]

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

  • aa9f0f779507Revision changes
    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added ai_overview_paid discriminator mapping keys to the ///////////////////////////// response property for the response status

  • 5ca55b1d9811Revision changes
    • breaking

      the request property ///// became not nullable

    • breaking

      the request property ///// became not nullable

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • warning

      removed the request property /////