# SocialCrawl API: content_analysis endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/content_analysis

## GET /v1/content_analysis/search
Search web citations of a keyword with per-mention sentiment
Credit cost: 20 (override; tier advanced)
Parameters:
- keyword (required): Brand or term to find mentions of. Wrap in escaped double-quotes for an exact phrase (e.g. "logitech mouse").
- page_type (optional, enum: ecommerce | news | blogs | message-boards | organization): Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization. Translated to a page_types filter upstream.
- search_mode (optional, enum: as_is | one_per_domain): as_is (default) returns every matching page; one_per_domain dedupes to the top page per domain.
- limit (optional, integer): Number of citations to return per page (1-100, default 10). Paginate via `cursor` for more.
- cursor (optional, string): Opaque pagination cursor: pass the `next_cursor` from the previous response to fetch the next page.
- order_by (optional, string): Sort rules as "field,direction"; separate multiple rules with ";" (e.g. content_info.sentiment_connotations.anger,desc).
- filters (optional, string): Advanced filter expression as a JSON array (≤8 conditions). Combined with page_type via AND when both are present.
curl -G "https://www.socialcrawl.dev/v1/content_analysis/search" \
  --data-urlencode "keyword=openai" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/content_analysis/summary
Aggregate mention summary for a keyword
Credit cost: 20 (override; tier advanced)
Parameters:
- keyword (required): Brand or term to summarize.
- page_type (optional, enum: ecommerce | news | blogs | message-boards | organization): Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization.
- positive_connotation_threshold (optional, string): Minimum positive-connotation probability (0-1, default 0.4) for a mention to count as positive.
- sentiments_connotation_threshold (optional, string): Minimum sentiment-connotation probability (0-1, default 0.4) for the 6-axis emotion buckets.
- internal_list_limit (optional, integer): Cap on internal arrays such as top_domains / categories (1-20).
- filters (optional, string): Advanced filter expression as a JSON array (≤8 conditions).
curl -G "https://www.socialcrawl.dev/v1/content_analysis/summary" \
  --data-urlencode "keyword=openai" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/content_analysis/sentiment
Sentiment breakdown for a keyword
Credit cost: 20 (override; tier advanced)
Parameters:
- keyword (required): Brand or term to analyze.
- page_type (optional, enum: ecommerce | news | blogs | message-boards | organization): Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization.
- positive_connotation_threshold (optional, string): Minimum positive-connotation probability (0-1, default 0.4).
- filters (optional, string): Advanced filter expression as a JSON array (≤8 conditions).
curl -G "https://www.socialcrawl.dev/v1/content_analysis/sentiment" \
  --data-urlencode "keyword=openai" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/content_analysis/rating-distribution
Rating histogram for a keyword
Credit cost: 20 (override; tier advanced)
Parameters:
- keyword (required): Product or term to build the rating histogram for.
- page_type (optional, enum: ecommerce | news | blogs | message-boards | organization): Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization.
- filters (optional, string): Advanced filter expression as a JSON array (≤8 conditions).
curl -G "https://www.socialcrawl.dev/v1/content_analysis/rating-distribution" \
  --data-urlencode "keyword=iphone" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/content_analysis/phrase-trends
Keyword mention volume + sentiment over time
Credit cost: 20 (override; tier advanced)
Parameters:
- keyword (required): Brand or term to trend.
- date_from (required): Start of the date range (yyyy-mm-dd).
- date_to (optional, string): End of the date range (yyyy-mm-dd); defaults to today.
- date_group (optional, enum: day | week | month): Bucket size: day, week, or month (default month).
- page_type (optional, enum: ecommerce | news | blogs | message-boards | organization): Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization.
- internal_list_limit (optional, integer): Cap on internal arrays per bucket (1-20).
- filters (optional, string): Advanced filter expression as a JSON array (≤8 conditions).
curl -G "https://www.socialcrawl.dev/v1/content_analysis/phrase-trends" \
  --data-urlencode "keyword=openai" \
  --data-urlencode "date_from=2025-01-01" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/content_analysis/category-trends
Category mention volume + sentiment over time
Credit cost: 20 (override; tier advanced)
Parameters:
- category_code (required): Numeric category code from the /content_analysis/categories taxonomy (e.g. 10021 = Apparel).
- date_from (required): Start of the date range (yyyy-mm-dd).
- date_to (optional, string): End of the date range (yyyy-mm-dd); defaults to today.
- date_group (optional, enum: day | week | month): Bucket size: day, week, or month (default month).
- internal_list_limit (optional, integer): Cap on internal arrays per bucket (1-20).
- filters (optional, string): Advanced filter expression as a JSON array (≤8 conditions) over the citation fields listed by /content_analysis/filters, applied before the buckets are counted. Example: [["country","=","DE"]] for German-hosted citations, or [["language","=","de"]] for German-language ones.
curl -G "https://www.socialcrawl.dev/v1/content_analysis/category-trends" \
  --data-urlencode "category_code=10021" \
  --data-urlencode "date_from=2025-01-01" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/content_analysis/languages
List supported Content Analysis languages
Credit cost: 1 (standard)
curl "https://www.socialcrawl.dev/v1/content_analysis/languages" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/content_analysis/locations
List supported Content Analysis locations
Credit cost: 1 (standard)
curl "https://www.socialcrawl.dev/v1/content_analysis/locations" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/content_analysis/categories
List the Content Analysis category taxonomy
Credit cost: 1 (standard)
curl "https://www.socialcrawl.dev/v1/content_analysis/categories" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/content_analysis/filters
List the filterable fields for Content Analysis
Credit cost: 1 (standard)
curl "https://www.socialcrawl.dev/v1/content_analysis/filters" \
  -H "x-api-key: YOUR_API_KEY"