# Content Analysis (/docs/content_analysis)



Content Analysis [#content-analysis]

Web-wide **brand listening + sentiment intelligence**, powered by DataForSEO's citation
database. Search every web page (news, blogs, ecommerce, message boards, organization sites)
that mentions a keyword, each scored on a 6-axis emotional model (anger, happiness, love,
sadness, share, fun) plus positive/negative/neutral probabilities — then roll it up into totals,
top domains, rating histograms, and sentiment-over-time trends.

This is **page-level web citation data, not native platform posts** — it complements the
per-platform scrapers with cross-web sentiment you can't get from any single social API.

Base URL: `/v1/content_analysis/...`

<Callout>
  The six keyword-driven endpoints are 

  **20 credits each**

  , a flat cost that overrides the advanced-tier ladder price. The four taxonomy endpoints are 1 credit. Budget on the endpoint, not the tier.
</Callout>

Getting started [#getting-started]

Every endpoint is a `GET` with `x-api-key` auth. Start with `summary` for a one-call roll-up, or
`/v1/content_analysis/search` for the raw mention feed:

```bash
curl "https://www.socialcrawl.dev/v1/content_analysis/summary?keyword=openai" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Narrow any keyword query to a page type with `page_type` (`news`, `blogs`, `ecommerce`,
`message-boards`, `organization`, comma-separated for several), and page the `search` feed with
the `cursor` returned as `next_cursor`. Sentiment values are DataForSEO's model-derived NLP,
passed through verbatim.

Pick the endpoint by the shape of the answer [#pick-the-endpoint-by-the-shape-of-the-answer]

All six keyword endpoints read the same citation index. They differ in what they hand back, and
because each is a full 20-credit call, choosing the right one matters more here than on most
platforms.

* **`summary`** — one object describing a keyword's whole web presence: total mention count, top
  domains, sentiment splits, and breakdowns by page type, country and language. This is the
  right first call on any new keyword.
* **`search`** — the individual mentions, each with its page, snippet and per-mention sentiment
  scores. `limit` runs 1-100 (default 10) and `cursor` pages deeper.
  `search_mode=one_per_domain` collapses to the single strongest page per domain, which is what
  you want when one site is flooding the results; `as_is` (the default) returns everything.
* **`/v1/content_analysis/sentiment`** — the sentiment breakdown alone, both the
  positive/negative/neutral split and the six emotional axes, with no domains or geography
  attached. Use it when sentiment is the only field you read.
* **`/v1/content_analysis/rating-distribution`** — a ten-bucket histogram of the star ratings
  found in the mentions, with the sentiment, domains and categories inside each bucket. It
  answers "how does the language differ between the people who rated this well and the people
  who rated it badly", which is a review-heavy, product-shaped question.
* **`phrase-trends`** — mention volume and sentiment as a time series for one keyword. Requires
  `date_from`; `date_to` defaults to today and `date_group` buckets by `day`, `week` or `month`
  (default `month`).
* **`category-trends`** — the same time series for an entire content category rather than a
  keyword, keyed on a numeric `category_code`.

```bash
# Weekly mention volume and sentiment for a brand across six months
curl "https://www.socialcrawl.dev/v1/content_analysis/phrase-trends?keyword=notion&date_from=2026-02-01&date_group=week" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

The four taxonomy endpoints [#the-four-taxonomy-endpoints]

These describe the index rather than query it, cost 1 credit each, and are worth calling once
and caching.

`categories` returns the full category taxonomy with each entry's code, name and parent — this
is where the `category_code` that `category-trends` requires comes from, and it also decodes the
numeric category values attached to individual mentions. `/v1/content_analysis/languages` and
`/v1/content_analysis/locations` return the supported language codes and locations, which is how
you read the `language` and `country` fields on a mention. `/v1/content_analysis/filters`
returns the fields you are allowed to filter on and the value type each accepts.

```bash
# 1. Find the category code
curl "https://www.socialcrawl.dev/v1/content_analysis/categories" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# 2. Trend that whole category
curl "https://www.socialcrawl.dev/v1/content_analysis/category-trends?category_code=10021&date_from=2026-01-01" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Advanced filtering [#advanced-filtering]

Beyond `page_type`, the keyword endpoints accept `filters` — a DataForSEO filter expression
passed as a JSON array of up to eight conditions. Call `filters` first to see which fields are
filterable and what each expects. When both `filters` and `page_type` are present they are
combined with `AND`. `search` additionally accepts `order_by` as `"field,direction"` pairs
separated by `;`, so `order_by=content_info.sentiment_connotations.anger,desc` surfaces the
angriest mentions first.

Two thresholds control how mentions are bucketed rather than which are returned:
`positive_connotation_threshold` (0-1, default 0.4) sets the probability at which a mention
counts as positive, and `sentiments_connotation_threshold` does the same for the six emotional
buckets on `summary`. Raise them for a stricter read; lower them if the neutral bucket is
swallowing everything.

Endpoints [#endpoints]

<PlatformEndpoints platform="content_analysis" />

Read this before you build [#read-this-before-you-build]

**Escape quotes for exact phrases.** `keyword` matches loosely by default. Wrap the term in
escaped double quotes — `keyword="logitech mouse"` — to match the phrase rather than the words.

**`internal_list_limit` caps the arrays inside a response**, such as `top_domains` and
`categories` on `summary` or the per-bucket lists on the trend endpoints. It runs 1-20 and does
not change the price.

**This index is not the social platforms.** A page that quotes a tweet is a citation; the tweet
itself is not. For native platform posts use the per-platform endpoints or
[`/v1/search/everywhere`](/docs/search/everywhere.md).

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema
* Only `search` paginates; the aggregate endpoints return one object per call
* `phrase-trends` and `category-trends` both require `date_from` and reject a range they cannot
  bucket, before billing