> ## 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.

# Read country activity

> Country publication aggregates and hourly evidence from the shared activity journal. Additions, updates and linked entities are separate metrics. Facility additions count published registry records (units), not newly built or deduplicated physical sites; country context inventories expose site and unit totals separately. All matching countries are included; this map is independent of evidence pagination. Source collection gaps remain explicit: unknown or withheld source counts are null in both country and hourly rows. meta.coverage.window_complete distinguishes an initialized journal from history covering the selected window; hourly_window_complete covers the entire timeline day. Actor-direction edges use Event occurrence dates, separately from publication activity. meta.edges_coverage exposes availability, status and oldest serving snapshot as_of; unavailable snapshots do not imply zero relationships.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/countries
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/countries:
    get:
      tags:
        - Geography
      summary: Read country activity
      description: >-
        Country publication aggregates and hourly evidence from the shared
        activity journal. Additions, updates and linked entities are separate
        metrics. Facility additions count published registry records (units),
        not newly built or deduplicated physical sites; country context
        inventories expose site and unit totals separately. All matching
        countries are included; this map is independent of evidence pagination.
        Source collection gaps remain explicit: unknown or withheld source
        counts are null in both country and hourly rows.
        meta.coverage.window_complete distinguishes an initialized journal from
        history covering the selected window; hourly_window_complete covers the
        entire timeline day. Actor-direction edges use Event occurrence dates,
        separately from publication activity. meta.edges_coverage exposes
        availability, status and oldest serving snapshot as_of; unavailable
        snapshots do not imply zero relationships.
      operationId: list-countries-v2
      parameters:
        - name: time_basis
          in: query
          required: false
          schema:
            type: string
            enum:
              - published
              - recorded
            default: published
          description: >-
            Clock for date/hour filters and ordering: published preserves the
            serving/reference publication time; recorded uses the durable
            journal commit time and includes late publications when they become
            available. Omission retains published compatibility. Choose recorded
            explicitly for ongoing activity Monitors; source dates remain
            unchanged. Full value list:
            https://docs.gdeltcloud.com/reference/enums#activity-time-basis
          example: recorded
        - name: date_start
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            First UTC date in the selected time_basis. Defaults to today; future
            dates are rejected. Neither clock is Event occurrence time. 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-09-06'
        - name: date_end
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Last UTC date in the selected time_basis, inclusive. Defaults to
            date_start and cannot be later than the current UTC day. 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-09-06'
        - name: hour
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 23
          description: >-
            Optional UTC hour, 0–23. Requires a single date and rejects hours
            that have not started. The current hour is allowed and describes
            publications so far; omit for the whole selected day.
          example: '14'
        - name: country
          in: query
          required: false
          schema:
            type: string
          description: >-
            Known country attribution. Evidence distinguishes location, actor
            origin, reporting and source association. Note: validation is owned
            by the endpoint service because it depends on composed or
            cross-parameter state; the published error semantics above still
            apply. Full value list:
            https://docs.gdeltcloud.com/reference/enums#country
          example: TWN
        - name: basis
          in: query
          required: false
          schema:
            type: string
            default: publication
          description: >-
            publication retains the activity journal clock. reporting uses
            distinct served Events by occurrence date and location country
            (country_match=location), and Stories by reporting date under every
            authoritative country association (the Stories summary
            country_attribution=all mode). Country buckets may overlap for
            Stories; totals are computed independently. Reporting has day
            precision and rejects hour. 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: reporting
        - name: include_event_metrics
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            Include Event metric maxima with tied-country evidence, five
            AI-coded metric averages with scored Event counts, and per-country
            readings/linked identity counts. Reporting basis only;
            occurrence-date and location scope. Averages weight each finite
            scored canonical Event equally, independently of directory
            pagination. Unrestricted world averages include unlocated Events;
            geographic filters use location. Goldstein remains a signed maximum
            only. No scored observations gives null/count 0; unavailable context
            remains null.
          example: 'true'
        - name: include_context
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            Include dated macro rollups for the selected geography, with
            same-period coverage and aggregation methods. Requires intelligence
            entitlement.
          example: 'true'
        - name: directory
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            Enumerate every registered country, including countries without
            observed activity; supports search, geography, sort and pagination.
          example: 'true'
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Country directory name or ISO code search. Requires directory=true.
          example: Taiwan
        - 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: >-
            Registered region scope. Note: validation is owned by the endpoint
            service because it depends on composed or cross-parameter state; the
            published error semantics above still apply. Full value list:
            https://docs.gdeltcloud.com/reference/enums#region
          example: East Asia
        - name: continent
          in: query
          required: false
          schema:
            type: string
            enum:
              - Africa
              - Asia
              - Europe
              - North America
              - South America
              - Oceania
          description: >-
            Registered continent scope. Note: validation is owned by the
            endpoint service because it depends on composed or cross-parameter
            state; the published error semantics above still apply. Full value
            list: https://docs.gdeltcloud.com/reference/enums#continent
          example: Asia
        - name: sort
          in: query
          required: false
          schema:
            type: string
          description: >-
            Directory order: name alphabetically (default in directory mode),
            events or stories descending with stable name ties. Requires
            directory=true. 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: name
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 250
          description: >-
            Countries per directory page (default 25 in directory mode).
            Requires directory=true; otherwise this parameter is rejected. 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: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
          description: >-
            Directory row offset (default 0 in directory mode). Requires
            directory=true.
          example: '0'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountriesResponse'
              examples:
                default:
                  summary: Today so far
                  value:
                    success: true
                    data: []
        '400':
          description: Invalid or unsupported parameter (see `code` and `details`)
        '401':
          description: Missing or invalid API key
        '403':
          description: Plan does not include this surface
        '404':
          description: Not found
        '429':
          description: Quota or rate limit exceeded
        '500':
          description: Server error
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CountriesResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: array
          items:
            type: object
            properties:
              iso3:
                type: string
              name:
                type: string
              events:
                type: number
                nullable: true
              stories:
                type: number
                nullable: true
              entities:
                type: number
                nullable: true
              facilities:
                type: number
                nullable: true
                description: >-
                  Added facility registry records (units), not deduplicated
                  physical sites. Country context inventories expose site and
                  unit counts separately.
              list_entries:
                type: number
                nullable: true
              office_holders:
                type: number
                nullable: true
              updates:
                type: number
                nullable: true
              removals:
                type: number
                nullable: true
              entities_spotted:
                type: number
                nullable: true
              latest_publication:
                type: string
                nullable: true
              region:
                type: string
                nullable: true
              continent:
                type: string
                nullable: true
            required:
              - iso3
              - name
              - events
              - stories
              - entities
              - facilities
              - list_entries
              - office_holders
              - updates
              - removals
              - entities_spotted
              - latest_publication
        edges:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              target:
                type: string
              event_count:
                type: number
              evidence_event_ids:
                type: array
                items:
                  type: string
            required:
              - source
              - target
              - event_count
              - evidence_event_ids
        hourly:
          type: array
          items:
            type: object
            additionalProperties: {}
        daily:
          type: array
          items:
            type: object
            additionalProperties: {}
        totals:
          type: object
          additionalProperties: {}
        applied_filters:
          type: object
          additionalProperties: {}
        meta:
          type: object
          additionalProperties: {}
        event_metrics:
          type: array
          items:
            type: object
            properties:
              metric:
                type: string
                enum:
                  - significance
                  - magnitude
                  - systemic_importance
                  - propagation_potential
                  - market_sensitivity
                  - confidence
                  - goldstein_scale
              value:
                type: number
                nullable: true
              countries:
                type: array
                items:
                  type: object
                  properties:
                    iso3:
                      type: string
                    event_uid:
                      type: string
                    title:
                      type: string
                    event_date:
                      type: string
                  required:
                    - iso3
                    - event_uid
                    - title
                    - event_date
            required:
              - metric
              - value
              - countries
          nullable: true
          description: >-
            Maximum signed Event metrics by occurrence date, with evidence from
            every tied country.
        event_metric_averages:
          type: array
          items:
            type: object
            properties:
              metric:
                type: string
                enum:
                  - significance
                  - magnitude
                  - systemic_importance
                  - propagation_potential
                  - market_sensitivity
              value:
                type: number
                nullable: true
                description: >-
                  Arithmetic mean of finite scored canonical Event observations
                  in the selected occurrence-date/location scope; null when
                  scored_event_count is zero.
              scored_event_count:
                type: number
                description: >-
                  Number of canonical Events with a finite non-null observation
                  for this metric; the mean denominator. A known zero score is
                  included.
            required:
              - metric
              - value
              - scored_event_count
          nullable: true
          description: >-
            Five AI-coded metric means weighted by scored Event observations,
            never country means or maxima. Independent of directory pagination.
            World scope includes unlocated Events; geographic filters use Event
            location. Null when context is unavailable or not requested.
        event_metrics_by_country:
          type: array
          items:
            type: object
            properties:
              iso3:
                type: string
                nullable: true
              maxima:
                type: array
                items:
                  type: object
                  properties:
                    metric:
                      type: string
                    value:
                      type: number
                      nullable: true
                    event:
                      type: object
                      properties:
                        event_uid:
                          type: string
                        title:
                          type: string
                        event_date:
                          type: string
                      required:
                        - event_uid
                        - title
                        - event_date
                      nullable: true
                  required:
                    - metric
                    - value
                    - event
              averages:
                type: array
                items:
                  type: object
                  properties:
                    metric:
                      type: string
                      enum:
                        - significance
                        - magnitude
                        - systemic_importance
                        - propagation_potential
                        - market_sensitivity
                    value:
                      type: number
                      nullable: true
                      description: >-
                        Arithmetic mean of finite scored canonical Event
                        observations in the selected occurrence-date/location
                        scope; null when scored_event_count is zero.
                    scored_event_count:
                      type: number
                      description: >-
                        Number of canonical Events with a finite non-null
                        observation for this metric; the mean denominator. A
                        known zero score is included.
                  required:
                    - metric
                    - value
                    - scored_event_count
            required:
              - iso3
              - maxima
          nullable: true
        context:
          type: object
          properties:
            status:
              type: string
              enum:
                - available
                - unavailable
                - withheld
            measured_at:
              type: string
            note:
              type: string
            fundamentals:
              type: array
              items:
                type: object
                properties:
                  indicator_code:
                    type: string
                  label:
                    type: string
                  value:
                    type: number
                    nullable: true
                  units:
                    type: string
                  period:
                    type: string
                    nullable: true
                  method:
                    type: string
                  countries_observed:
                    type: number
                  countries_total:
                    type: number
                  country_iso3s:
                    type: array
                    items:
                      type: string
                  sources:
                    type: array
                    items:
                      type: string
                  observation_status:
                    type: array
                    items:
                      type: string
                required:
                  - indicator_code
                  - label
                  - value
                  - units
                  - period
                  - method
                  - countries_observed
                  - countries_total
                  - country_iso3s
                  - sources
                  - observation_status
              nullable: true
          required:
            - status
            - fundamentals
        pagination:
          type: object
          additionalProperties: {}
      required:
        - success
        - data
        - edges
        - hourly
        - totals
        - applied_filters
        - meta
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````