Compare how subjects are spoken of

Sets two to five entities’ or companies’ share of voice by one speaker statement characteristics axis side by side, over the same window, speakers and filter: how NVIDIA is spoken of next to AMD and Intel. Each subject is exactly the split GET /v1/podcasts/mentions/share-of-voice returns for it with by set to the axis: one group per label, each a share of the subject’s scored_mentions and flagged low_sample below 20. Subjects are returned in the order given. A subject that matches nothing, or a company with no linked entity, is a 422 naming it. by defaults to sentiment; breakdown splits each label group by a second axis. For which professions say it, use the share of voice with by=occupation, one subject at a time.

GET /v1/podcasts/mentions/share-of-voice/compare

cURL

cURL

curl -H "X-API-Key: $PARTICLE_API_KEY" \
  "https://api.particle.pro/v1/podcasts/mentions/share-of-voice/compare?by=sentiment&speakers=all"

200

{
  "by": "sentiment",
  "end": "<string>",
  "speakers": "all",
  "start": "<string>",
  "subjects": [
    {
      "attributed_mentions": 123,
      "by": "occupation",
      "end": "<string>",
      "groups": [
        {
          "code": "<string>",
          "episodes": 123,
          "mentions": 123,
          "share": 123,
          "speakers": 123,
          "title": "<string>",
          "breakdown": [
            {
              "label": "<string>",
              "mentions": 123,
              "share": 123,
              "examples": [
                {
                  "episode": {
                    "id": "<string>",
                    "title": "<string>",
                    "podcast": {
                      "id": "<string>",
                      "title": "<string>",
                      "best_rank": {
                        "captured_at": "2023-11-07T05:31:56Z",
                        "chart_type": "top_podcasts",
                        "rank": 123,
                        "source": "apple",
                        "category_slug": "<string>",
                        "country": "<string>"
                      },
                      "image_url": "<string>",
                      "popularity": 123,
                      "publisher": {
                        "id": "<string>",
                        "name": "<string>",
                        "slug": "<string>"
                      },
                      "slug": "<string>"
                    },
                    "published_at": "2023-11-07T05:31:56Z",
                    "slug": "<string>",
                    "web_url": "<string>"
                  },
                  "line": {
                    "end_seconds": 123,
                    "number": 123,
                    "speaker": "<string>",
                    "start_seconds": 123,
                    "text": "<string>",
                    "is_match": true,
                    "is_mention": true,
                    "matched_terms": [
                      "<string>"
                    ],
                    "role": "<string>",
                    "segment_id": "<string>",
                    "speaker_statement_characteristics": {
                      "certainty": "hedged",
                      "sentiment": "negative",
                      "specificity": "vague",
                      "temporal_orientation": "past"
                    }
                  },
                  "start_seconds": 123,
                  "person": {
                    "id": "<string>",
                    "name": "<string>",
                    "description": "<string>",
                    "image_url": "<string>",
                    "slug": "<string>"
                  },
                  "url": "<string>"
                }
              ]
            }
          ],
          "buckets": [
            {
              "mentions": 123,
              "start": "<string>"
            }
          ],
          "examples": [
            {
              "episode": {
                "id": "<string>",
                "title": "<string>",
                "podcast": {
                  "id": "<string>",
                  "title": "<string>",
                  "best_rank": {
                    "captured_at": "2023-11-07T05:31:56Z",
                    "chart_type": "top_podcasts",
                    "rank": 123,
                    "source": "apple",
                    "category_slug": "<string>",
                    "country": "<string>"
                  },
                  "image_url": "<string>",
                  "popularity": 123,
                  "publisher": {
                    "id": "<string>",
                    "name": "<string>",
                    "slug": "<string>"
                  },
                  "slug": "<string>"
                },
                "published_at": "2023-11-07T05:31:56Z",
                "slug": "<string>",
                "web_url": "<string>"
              },
              "line": {
                "end_seconds": 123,
                "number": 123,
                "speaker": "<string>",
                "start_seconds": 123,
                "text": "<string>",
                "is_match": true,
                "is_mention": true,
                "matched_terms": [
                  "<string>"
                ],
                "role": "<string>",
                "segment_id": "<string>",
                "speaker_statement_characteristics": {
                  "certainty": "hedged",
                  "sentiment": "negative",
                  "specificity": "vague",
                  "temporal_orientation": "past"
                }
              },
              "start_seconds": 123,
              "person": {
                "id": "<string>",
                "name": "<string>",
                "description": "<string>",
                "image_url": "<string>",
                "slug": "<string>"
              },
              "url": "<string>"
            }
          ],
          "low_sample": true,
          "scored_mentions": 123,
          "top": {
            "code": "<string>",
            "share": 123,
            "title": "<string>"
          }
        }
      ],
      "host_mentions": 123,
      "mentions": 123,
      "speaker_mentions": 123,
      "speakers": "all",
      "start": "<string>",
      "breakdown": "sentiment",
      "characteristics_version": "<string>",
      "company": {
        "id": "<string>",
        "name": "<string>",
        "description": "<string>",
        "domain": "<string>",
        "image_url": "<string>",
        "slug": "<string>",
        "ticker": "<string>"
      },
      "entity": {
        "id": "<string>",
        "name": "<string>",
        "slug": "<string>",
        "company": {
          "id": "<string>",
          "domain": "<string>",
          "ticker": "<string>"
        },
        "description": "<string>",
        "image_url": "<string>",
        "person": {
          "id": "<string>",
          "company": "<string>",
          "image_url": "<string>",
          "title": "<string>"
        },
        "type": {
          "name": "<string>",
          "slug": "<string>"
        },
        "wikipedia_url": "<string>"
      },
      "keyword": "<string>",
      "level": "major",
      "scored_mentions": 123
    }
  ],
  "breakdown": "sentiment",
  "characteristics_version": "<string>"
}

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Query Parameters

entity_id · string[] | null

Two to five entity slugs (e.g., 'sam-altman') or IDs, comma-separated, in the order to compare them. One of entity_id or company_id is required.

Example:

["sam-altman", "dario-amodei"]

company_id · string[] | null

Two to five company slugs, domains, or IDs, comma-separated, in the order to compare them. Each resolves to the company's linked entity. One of entity_id or company_id is required.

Example:

["nvidia", "amd", "intel"]

keyword_search · string

Not accepted: speaker statement characteristics are read on an entity's or a company's mentions, not on the lines that say a keyword, so passing it returns 422.

Maximum string length: 500

by · enum<string> · default: sentiment

The speaker statement characteristics axis whose labels each subject's lines are grouped by: by=sentiment is how negatively or positively each subject was spoken of.

Available options: sentiment, certainty, specificity, temporal_orientation

speakers · enum<string> · default: all

Attribute every speaker's lines, hosts included, or guests' and panelists' only.

Available options: all, guests

podcast_id · string

Restrict to mentions inside one podcast.

publisher_id · string

Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID.

include_ads · boolean

Mentions inside ad reads are excluded by default. Pass true to include them.

since · string

Only episodes published on or after this date. Defaults to 30 days before until; the window may span at most 365 days.

Example:

"2026-09-01"

until · string

Only episodes published on or before this date. Defaults to now.

Example:

"2026-10-01"

published_after · string · deprecated

Deprecated alias of since.

published_before · string · deprecated

Deprecated alias of until.

breakdown · enum<string>

Also split each label group's lines by their label on this second axis: by=temporal_orientation&breakdown=certainty is how sure each subject's predictions are. Must differ from by.

Available options: sentiment, certainty, specificity, temporal_orientation

speaker_statement_characteristics · object

Count only mentions said a certain way, for every subject: speaker_statement_characteristics[temporal_orientation]=future compares how each subject's predictions lean. Each key is an axis (sentiment, certainty, specificity, temporal_orientation) and its value one or more of that axis's labels, comma-separated: labels on one axis match any of them, and axes combine with AND.

Show child attributes

Response

200

application/json

OK

by · enum<string> · required

The speaker statement characteristics axis whose labels every subject's groups are.

Available options: sentiment, certainty, specificity, temporal_orientation

end · string · required

Day the window ends (UTC), excluded: the window is [start, end).

speakers · enum<string> · required

Whose lines every subject's groups count: every speaker's, or guests' and panelists' only.

Available options: all, guests

start · string · required

First day of the window (UTC), included.

subjects · object[] | null · required

One split per subject, in the order requested, each exactly what GET /v1/podcasts/mentions/share-of-voice returns for that subject with the same parameters.

Show child attributes

breakdown · enum<string>

The axis each label group's lines are split by, when breakdown was given.

Available options: sentiment, certainty, specificity, temporal_orientation

characteristics_version · string

Opaque version of the speaker statement characteristics every subject read. Absent when no subject read any, or when they read different versions: compare subjects only when it is present.