Sign in
ContentAnalysis

Changed on

‌ This endpoint will provide you with rating distribution data for the keyword and other parameters specified in the request.

post/v3/content_analysis/rating_distribution/live

Request

  • Base URL: https://api.dataforseo.com
  • URL: https://api.dataforseo.com/v3/content_analysis/rating_distribution/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>

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>

search_modestring nullable

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

positive_connotation_thresholdnumber nullable

<em>positive connotation threshold</em><br>optional field<br>specified as the probability index threshold for positive sentiment related to the citation content<br>if you specify this field, <code>connotation_types</code> object in the response will only contain data on citations with <code>positive</code> sentiment probability more than or equal to the specified value<br>possible values: from <code>0</code> to <code>1</code><br>default value: <code>0.4</code>

sentiments_connotation_thresholdnumber nullable

<em>sentiment connotation threshold</em><br>optional field<br>specified as the probability index threshold for sentiment connotations related to the citation content<br>if you specify this field, <code>sentiment_connotations</code> object in the response will only contain data on citations where the probability per each sentiment is more than or equal to the specified value<br>possible values: from <code>0</code> to <code>1</code><br>default value: <code>0.4</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",
    "internal_list_limit": 10
  }
]

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

  • be20fca9d9ccRevision changes
    • info

      api operation id ContentAnalysisRatingDistributionLive removed and replaced with RatingDistributionLive

  • e73495840d61Revision changes
    • info

      api operation id RatingDistributionLive removed and replaced with ContentAnalysisRatingDistributionLive