Sign in
ContentAnalysis

Changed on

‌ This endpoint will provide you with data on all citations of the target keyword for the indicated date range.

post/v3/content_analysis/phrase_trends/live

Request

  • Base URL: https://api.dataforseo.com
  • URL: https://api.dataforseo.com/v3/content_analysis/phrase_trends/live
  • Auth: HTTP basic

Request body

keywordstring

<em>target keyword</em><br><strong>required field</strong><br>UTF-8 encoding<br>the keywords will be converted to a lowercase format;<br><strong>Note</strong>: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; <br>example: <br><code>"keyword": ""tesla palo alto""</code><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>

keyword_fieldsobject nullable

<em>target keyword fields and target keywords</em><br>optional field<br>use this parameter to filter the dataset by keywords that certain fields should contain;<br>fields you can specify: <code>title</code>, <code>main_title</code>, <code>previous_title</code>, <code>snippet</code><br>you can indicate several fields;<br><strong>Note</strong>: to match an exact phrase instead of a stand-alone keyword, use double quotes and backslashes; <br>example:<br>"keyword_fields": {<br>"snippet": "\"logitech mouse\"",<br>"main_title": "sale"<br>}

page_typestring[] nullable

<em>target page types</em><br>optional field<br>use this parameter to filter the dataset by page types<br>possible values: <br><code>"ecommerce"</code>, <code>"news"</code>, <code>"blogs"</code>, <code>"message-boards"</code>, <code>"organization"</code>

search_modestring nullable

<em>results grouping type</em><br>optional field<br>possible grouping types:<br><code>as_is</code> - returns data on all citations for the target <code>keyword</code><br><code>one_per_domain</code> - returns data on one citation of the <code>keyword</code> per domain<br>default value: <code>as_is</code>

internal_list_limitinteger nullable

<em>maximum number of elements within internal arrays</em><br>optional field<br>you can use this field to limit the number of elements within the following arrays:<br><code>top_domains</code><br><code>text_categories</code><br><code>page_categories</code><br><code>countries</code><br><code>languages</code><br>default value: <code>1</code><br>maximum value: <code>20</code>

date_fromstring

<em>starting date of the time range</em><br><strong>required field</strong><br>date format: <code>"yyyy-mm-dd"</code><br>example:<br><code>"2019-01-15"</code>

date_tostring nullable

<em>ending date of the time range</em><br>optional field<br>if you don't specify this field, today's date will be used by default<br>date format: <code>"yyyy-mm-dd"</code><br>example:<br><code>"2019-01-15"</code>

date_groupstring nullable

<em>time range which will be used to group the results</em><br>optional field<br>default value: <code>month</code><br>possible values: <code>day</code>, <code>week</code>, <code>month</code>

initial_dataset_filtersobject[] nullable

<em>initial dataset filtering parameters</em><br>optional field<br>initial filtering parameters that apply to fields in the <a href="/v3/content_analysis/search/live/?bash" target="_blank">Search endpoint</a>;<br><strong>you can add several filters at once (8 filters maximum);</strong><br>you should set a logical operator <code>and</code>, <code>or</code> between the conditions;<br>the following operators are supported:<br><code>regex</code>, <code>not_regex</code>, <code><</code>, <code><=</code>, <code>></code>, <code>>=</code>, <code>=</code>, <code><></code>, <code>in</code>, <code>not_in</code>, <code>like</code>,<code>not_like</code>, <code>has</code>, <code>has_not</code>, <code>match</code>, <code>not_match</code><br>you can use the <code>%</code> operator with <code>like</code> and <code>not_like</code> to match any string of zero or more characters;<br>example:<br><code>["domain","<>", "logitech.com"]</code><p><code>[["domain","<>","logitech.com"],"and",["content_info.connotation_types.negative",">",1000]]</code><p><code>[["domain","<&gt","logitech.com"]],<br>"and",<br>[["content_info.connotation_types.negative",">",1000],<br>"or",<p>["content_info.text_category","has",10994]]]</code><br>for more information about filters, please refer to <a href="/v3/content_analysis/filters" target="_blank" rel="noopener noreferrer">Content Analysis API - Filters</a><br>learn more about the initial dataset filters in <a href="https://dataforseo.com/help-center/what-are-the-initial-dataset-filters-and-how-do-they-work" rel="noopener noreferrer" target="_blank">this help center article.</a>

rank_scalestring nullable

<em>defines the scale used for calculating and displaying the <code>rank</code> values</em><br>optional field<p>you can use this parameter to choose whether rank values are presented on a 0–100 or 0–1000 scale<p>possible values:<br><code>one_hundred</code> — rank values are displayed on a 0–100 scale<br><code>one_thousand</code> — rank values are displayed on a 0–1000 scale<p>default value: <code>one_thousand</code><p>learn more about how this parameter works in <a href="https://dataforseo.com/help-center/using-the-rank_scale-parameter-in-content-analysis-api">this Help Center article</a>

tagstring nullable

<em>user-defined task identifier</em><br>optional field<br><em>the character limit is 255</em><br>you can use this parameter to identify the task and match it with the result<br>you will find the specified <code>tag</code> value in the <code>data</code> object of the response

Example request

[
  {
    "keyword": "logitech",
    "search_mode": "as_is",
    "date_from": "2022-09-01",
    "date_group": "month"
  }
]

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