> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gdeltcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Share of Voice

> Compare an entity’s share of canonical settled Story records within one explicit news denominator. Story membership and entity references come from the Core serving tables; unsupported article-level and upstream-salience weighting are not published.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/share-of-voice
openapi: 3.0.3
info:
  title: GDELT Cloud API v2
  version: 2.0.0
  description: >-
    Clean v2 REST API for generated GDELT Cloud structured Events, clustered
    Stories, linked Entities, summaries, admin1 discovery, significance ranking,
    and paginated article evidence.


    Event significance is a family-scoped weighted blend, renormalized so every
    event family spans a true 0-1: each event's raw total is divided by the
    maximum its own family can reach (Conflict 1.00, CAMEO+ POLITICAL 0.90,
    other CAMEO+ domains 0.65). All events: Goldstein severity 0.25, article
    evidence 0.05, confidence 0.05. Conflict only: fatalities 0.55 (log-scaled
    by body count) and civilian targeting 0.10. CAMEO+ only: magnitude 0.20,
    systemic importance 0.15, propagation potential 0.10, market sensitivity
    0.10. When magnitude is unmeasured its term AND its 0.20 weight are both
    dropped. The four CAMEO+ metrics are rubric scores produced by published
    formulas - ordinal ranking signals, not measurements, probabilities, or
    predicted price moves. goldstein_scale is one canonical public metric,
    populated for Conflict Events and CAMEO+ POLITICAL Events where meaningful.
    Story linked_event_count is a Story-to-Event link aggregate, not a distinct
    Event total.
servers:
  - url: https://gdeltcloud.com
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - ApiKeyAuth: []
tags:
  - name: Events
    description: Coded CAMEO+ / conflict events — search, fetch, and summarize.
  - name: Stories
    description: Clustered narratives (stories) and their articles.
  - name: Situations
    description: >-
      One real-world occurrence as the Stories and coded Events that belong to
      it — stored, adjudicated membership (`meta.situation_source: curated`) or
      a walked neighbourhood around a Story. Discovery, detail, four
      independently paged member lists, and the only write on the core surface
      (5 QU with an Idempotency-Key).
  - name: Entities
    description: >-
      People & organizations — resolve a name to an entity, then fetch its
      profile and tone. Also the publication activity journal
      (/api/v2/activity): observed evidence of what was published about
      identities and records — committed batches only, cursor-paged, never
      source intake.
  - name: Unified Search
    description: >-
      One fuzzy lookup across every id-space — start here with a name, take the
      entity id, then reuse it on every other surface. This is the resolver the
      rest of the API assumes you called first.
  - name: Media Intelligence
    description: >-
      Press-coverage tone over time and share of voice against a peer set.
      Requires the `can_use_tone` / `can_use_share_of_voice` entitlement; social
      signal is an admin-only preview.
  - name: Facilities
    description: >-
      Unified physical-asset directory — GEM energy assets, World Port Index
      ports and Epoch AI data centers on one keyed surface, resolved to spine
      owners. Requires the `can_use_facilities` entitlement.
  - name: Monitors
    description: >-
      Organization-shared scheduled checks over the Core API, with email and
      signed-webhook delivery. Monitor execution does not consume query units.
  - name: Geography
    description: >-
      Country context and admin-1 geography: /api/v2/countries (publication
      activity, reporting counts, dated economic and resource fundamentals,
      facility and office inventories, directory mode over every registered
      country) and admin-1 lookups.
  - name: Government
    description: >-
      US federal awards (USAspending) and foreign-influence registrations (DOJ
      NSD FARA), resolved onto the entity spine. Requires the `can_use_gov`
      entitlement.
  - name: Political Offices
    description: >-
      Public political offices and who holds them — legislatures, cabinets,
      heads of state, courts and IGO posts, with the office start/end dates the
      publisher states (valid time), resolved onto the entity spine. Actor
      context for geopolitical analysis; NOT a PEP or sanctions-screening tool.
      Requires the `can_use_offices` entitlement.
  - name: Filings
    description: >-
      SEC EDGAR filings, XBRL financials, and relations extracted from filing
      text. Requires the `can_use_filings` entitlement.
  - name: Reference Data
    description: >-
      The GLEIF Global LEI Index — legal-entity reference data, consolidation
      relationships, and LEI↔ISIN mappings. Requires the `can_use_gleif`
      entitlement.
  - name: Energy
    description: Global Energy Monitor assets + ownership registry.
  - name: AI Compute
    description: >-
      Epoch AI datasets — models, hardware, data centers, companies and chip
      sales. Requires the `can_use_epoch_ai` entitlement.
  - name: Macro Finance
    description: >-
      FRED economic time series — catalog, point-in-time observations and
      releases. Requires the `can_use_macro` entitlement.
  - name: Screening and Reference
    description: >-
      Restricted-party lists, name screening and ownership-chain exposure.
      Requires the `can_use_screening` / `can_use_exposure` entitlement.
      Analytical coverage, not an audit-grade compliance control.
  - name: China
    description: >-
      China overseas development finance (AidData GCDF). Requires the
      `can_use_china` entitlement.
  - name: Maritime
    description: >-
      AIS-derived vessel flow — chokepoint transits, last-known vessel
      positions, carriers, dwell and AIS-dark gaps. Terrestrial AIS only, so
      coverage thins in open ocean. Requires the `can_use_maritime` entitlement.
  - name: Atlas Intelligence
    description: >-
      Geopolitical-risk and posture indices computed from GDELT Cloud’s own
      coded events, normalized to each place’s own frozen baseline.
  - name: Briefs
    description: Source-backed monitoring briefs.
  - name: Meta
    description: >-
      Machine-readable discovery: the value vocabularies, the endpoint
      contracts, and the query-unit cost model. Unmetered, so a client can check
      before it spends.
paths:
  /api/v2/share-of-voice:
    get:
      tags:
        - Entities
      summary: Share of Voice
      description: >-
        Compare an entity’s share of canonical settled Story records within one
        explicit news denominator. Story membership and entity references come
        from the Core serving tables; unsupported article-level and
        upstream-salience weighting are not published.
      operationId: get-share-of-voice-v2
      parameters:
        - name: query
          in: query
          required: false
          schema:
            type: string
          description: >-
            Semantic denominator query. Note: validation is owned by the
            endpoint service because it depends on composed or cross-parameter
            state; the published error semantics above still apply.
          example: oil supply disruption
        - name: topic
          in: query
          required: false
          schema:
            type: string
          description: >-
            Lexical denominator topic. Note: validation is owned by the endpoint
            service because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: shipping
        - name: category
          in: query
          required: false
          schema:
            type: string
          description: >-
            Story or event category denominator. Note: validation is owned by
            the endpoint service because it depends on composed or
            cross-parameter state; the published error semantics above still
            apply.
          example: Battles
        - name: country
          in: query
          required: false
          schema:
            type: string
          description: >-
            Country denominator. Accepts an English name, ISO-2, or ISO-3. A
            Story matches when its own attributed countries include the value,
            or a linked Event is located there, or either linked Event actor
            originates there. Note: validation is owned by the endpoint service
            because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: NGA
        - name: region
          in: query
          required: false
          schema:
            type: string
            enum:
              - Africa
              - Asia
              - Middle East
              - Northern Africa
              - Western Africa
              - Eastern Africa
              - Middle Africa
              - Southern Africa
              - Europe
              - Eastern Europe
              - South Asia
              - Southeast Asia
              - East Asia
              - Central Asia
              - North America
              - Central America
              - Caribbean
              - South America
              - Oceania
          description: >-
            Region denominator. Note: validation is owned by the endpoint
            service because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: West Africa
        - name: continent
          in: query
          required: false
          schema:
            type: string
            enum:
              - Africa
              - Asia
              - Europe
              - North America
              - South America
              - Oceania
          description: >-
            Continent denominator. Note: validation is owned by the endpoint
            service because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: Africa
        - name: languages
          in: query
          required: false
          schema:
            type: string
          description: >-
            Language-code denominator. Note: validation is owned by the endpoint
            service because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: en,fr
        - name: source_set
          in: query
          required: false
          schema:
            type: string
          description: >-
            Source denominator. `all` selects the complete served Story corpus
            in the requested window; otherwise pass one or more article domains
            such as `reuters.com`. Note: validation is owned by the endpoint
            service because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: all
        - name: entities
          in: query
          required: false
          schema:
            type: string
          description: >-
            Entity identifiers. `entity_id` and `entity` are singular
            compatibility aliases. Also accepts: `entity_id`, `entity`. Note:
            validation is owned by the endpoint service because it depends on
            composed or cross-parameter state; the published error semantics
            above still apply.
          example: e_123,e_456
          x-aliases:
            - entity_id
            - entity
        - name: entity_query
          in: query
          required: false
          schema:
            type: string
          description: >-
            Entity-name resolver input. `entity_search`, `entity_terms`, and
            `numerator` are aliases. Also accepts: `entity_search`,
            `entity_terms`, `numerator`. Note: validation is owned by the
            endpoint service because it depends on composed or cross-parameter
            state; the published error semantics above still apply.
          example: Siemens
          x-aliases:
            - entity_search
            - entity_terms
            - numerator
        - name: run_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Previously materialized analytics run. Note: validation is owned by
            the endpoint service because it depends on composed or
            cross-parameter state; the published error semantics above still
            apply.
          example: run_123
        - name: denominator_hash
          in: query
          required: false
          schema:
            type: string
          description: >-
            Previously computed denominator identity. Note: validation is owned
            by the endpoint service because it depends on composed or
            cross-parameter state; the published error semantics above still
            apply.
          example: sha256
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            First occurrence date. `date_start` is an alias. Also accepts:
            `date_start`. Note: validation is owned by the endpoint service
            because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: '2026-08-01'
          x-aliases:
            - date_start
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Last occurrence date. `date_end` is an alias. Also accepts:
            `date_end`. Note: validation is owned by the endpoint service
            because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: '2026-08-21'
          x-aliases:
            - date_end
        - name: date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Single occurrence date. Note: validation is owned by the endpoint
            service because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: '2026-08-20'
        - name: days
          in: query
          required: false
          schema:
            type: string
          description: >-
            Trailing window. `window` is an alias. Also accepts: `window`. Note:
            validation is owned by the endpoint service because it depends on
            composed or cross-parameter state; the published error semantics
            above still apply.
          example: '30'
          x-aliases:
            - window
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          description: >-
            Maximum entity rows. Note: validation is owned by the endpoint
            service because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: '25'
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Pagination cursor. Note: validation is owned by the endpoint service
            because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: opaque
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: >-
            Legacy numeric offset. Note: validation is owned by the endpoint
            service because it depends on composed or cross-parameter state; the
            published error semantics above still apply.
          example: '0'
      responses:
        '200':
          description: Share of Voice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareOfVoiceResponse'
              examples:
                example_1:
                  summary: Apple share of the iPhone Story conversation
                  value:
                    success: true
                    data:
                      - run_id: null
                        bucket_date: '2026-08-20'
                        canonical_entity_id: wiki:4d35afdfc55573943161
                        display_name: Apple
                        entity_type: organization
                        wikipedia_url: https://en.wikipedia.org/wiki/Apple
                        entity_status: active
                        denominator_hash: 519ba0a349630668
                        denominator_profile_json: >-
                          {"scope":{"topic":"iPhone"},"start_date":"2026-08-20","end_date":"2026-08-20"}
                        denominator_story_count: 1
                        denominator_article_count: 1
                        entity_story_count: 1
                        story_share: 1
                        avg_tone_score: null
                        avg_risk_score: null
                        tone_coverage_ratio: 0
                        coverage_warnings:
                          - tone_not_yet_scored
                    status: available_live
                    start_date: '2026-08-20'
                    end_date: '2026-08-20'
                    entities:
                      - wiki:4d35afdfc55573943161
                    unresolved_terms: []
                    denominator:
                      hash: 519ba0a349630668
                      scope:
                        topic: iPhone
                      unit: story
                      validation: unvalidated_free_text
                      source: live_query
                      total_story_count: 1
                      total_article_count: 1
                      search_mode: structured_filters
                      semantic_min_score: null
                      semantic_candidate_limit: null
                      semantic_truncated: false
                    rows:
                      - run_id: null
                        bucket_date: '2026-08-20'
                        canonical_entity_id: wiki:4d35afdfc55573943161
                        display_name: Apple
                        entity_type: organization
                        wikipedia_url: https://en.wikipedia.org/wiki/Apple
                        entity_status: active
                        denominator_hash: 519ba0a349630668
                        denominator_profile_json: >-
                          {"scope":{"topic":"iPhone"},"start_date":"2026-08-20","end_date":"2026-08-20"}
                        denominator_story_count: 1
                        denominator_article_count: 1
                        entity_story_count: 1
                        story_share: 1
                        avg_tone_score: null
                        avg_risk_score: null
                        tone_coverage_ratio: 0
                        coverage_warnings:
                          - tone_not_yet_scored
                    methodology:
                      default_metric: story_share
                      denominator_required: true
                      note: >-
                        Share of voice is the share of settled Story records in
                        a defined conversation.
                      count_definitions:
                        entity_story_count: >-
                          Canonical eligible Story records whose settled
                          entity_refs include the resolved entity, or whose
                          settled headline fields contain its safe exact name.
        '401':
          description: Missing/invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Plan required (PLAN_REQUIRED) — the caller's plan does not carry
            `can_use_share_of_voice`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ShareOfVoiceResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: array
          items:
            type: object
            properties:
              run_id:
                type: string
                nullable: true
              bucket_date:
                type: string
              canonical_entity_id:
                type: string
              display_name:
                type: string
              entity_type:
                type: string
              wikipedia_url:
                type: string
              entity_status:
                type: string
              denominator_hash:
                type: string
              denominator_profile_json:
                type: string
              denominator_story_count:
                type: number
              denominator_article_count:
                type: number
              entity_story_count:
                type: number
              story_share:
                type: number
              avg_tone_score:
                type: number
                nullable: true
              avg_risk_score:
                type: number
                nullable: true
              tone_coverage_ratio:
                type: number
                nullable: true
              coverage_warnings:
                type: array
                items:
                  type: string
            required:
              - run_id
              - bucket_date
              - canonical_entity_id
              - display_name
              - entity_type
              - wikipedia_url
              - entity_status
              - denominator_hash
              - denominator_profile_json
              - denominator_story_count
              - denominator_article_count
              - entity_story_count
              - story_share
              - avg_tone_score
              - avg_risk_score
              - tone_coverage_ratio
              - coverage_warnings
        status:
          type: string
        start_date:
          type: string
        end_date:
          type: string
        entities:
          type: array
          items:
            type: string
        resolved_entities:
          type: array
          items:
            type: object
            additionalProperties:
              oneOf:
                - type: string
                - type: number
                - type: boolean
                - type: string
                  nullable: true
                - type: array
                  items:
                    type: string
        unresolved_terms:
          type: array
          items:
            type: string
        coverage: {}
        denominator:
          type: object
          properties:
            hash:
              type: string
            scope: {}
            unit:
              type: string
              enum:
                - story
            validation:
              type: string
            source:
              type: string
            total_story_count:
              type: number
            total_article_count:
              type: number
            search_mode:
              type: string
            semantic_min_score:
              type: number
              nullable: true
            semantic_candidate_limit:
              type: number
              nullable: true
            semantic_truncated:
              type: boolean
          required:
            - hash
            - scope
            - unit
            - validation
            - source
        applied_filters: {}
        rows:
          type: array
          items:
            type: object
            properties:
              run_id:
                type: string
                nullable: true
              bucket_date:
                type: string
              canonical_entity_id:
                type: string
              display_name:
                type: string
              entity_type:
                type: string
              wikipedia_url:
                type: string
              entity_status:
                type: string
              denominator_hash:
                type: string
              denominator_profile_json:
                type: string
              denominator_story_count:
                type: number
              denominator_article_count:
                type: number
              entity_story_count:
                type: number
              story_share:
                type: number
              avg_tone_score:
                type: number
                nullable: true
              avg_risk_score:
                type: number
                nullable: true
              tone_coverage_ratio:
                type: number
                nullable: true
              coverage_warnings:
                type: array
                items:
                  type: string
            required:
              - run_id
              - bucket_date
              - canonical_entity_id
              - display_name
              - entity_type
              - wikipedia_url
              - entity_status
              - denominator_hash
              - denominator_profile_json
              - denominator_story_count
              - denominator_article_count
              - entity_story_count
              - story_share
              - avg_tone_score
              - avg_risk_score
              - tone_coverage_ratio
              - coverage_warnings
        methodology:
          type: object
          properties:
            default_metric:
              type: string
              enum:
                - story_share
            denominator_required:
              type: boolean
            note:
              type: string
            count_definitions:
              type: object
              additionalProperties:
                type: string
          required:
            - default_metric
            - denominator_required
            - note
      required:
        - success
        - data
        - status
        - start_date
        - end_date
        - entities
        - denominator
        - rows
        - methodology
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
        code:
          type: string
        details:
          type: object
          description: >-
            Recoverable validation context when available, such as param,
            invalid_value, accepted_values, nearest_values, and a corrected
            example.
          additionalProperties: true
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````