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

# Get country context

> Country activity, dated economic/resource fundamentals, facilities and political-office inventories with evidence links. Unknown values remain null. Country association does not imply citizenship or headquarters. Counts of people, office-holder records, facilities and units are qualified separately.



## OpenAPI

````yaml /api-reference/openapi-v2.json get /api/v2/countries/{iso3}
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/{iso3}:
    get:
      tags:
        - Geography
      summary: Get country context
      description: >-
        Country activity, dated economic/resource fundamentals, facilities and
        political-office inventories with evidence links. Unknown values remain
        null. Country association does not imply citizenship or headquarters.
        Counts of people, office-holder records, facilities and units are
        qualified separately.
      operationId: get-country-v2
      parameters:
        - name: iso3
          in: path
          required: true
          schema:
            type: string
          description: The iso3.
        - 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: 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
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/CountryContextCard'
              examples:
                default:
                  summary: Taiwan country context
                  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:
    CountryContextCard:
      type: object
      properties:
        iso3:
          type: string
        name:
          type: string
        activity:
          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
          nullable: true
        hourly:
          type: array
          items:
            type: object
            additionalProperties: {}
        edges:
          type: array
          items:
            type: object
            additionalProperties: {}
        currencies:
          type: object
          properties:
            values:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  code:
                    type: string
                  numeric_code:
                    type: string
                  minor_units:
                    type: number
                    nullable: true
                required:
                  - name
                  - code
                  - numeric_code
                  - minor_units
              nullable: true
            source:
              type: string
            source_url:
              type: string
            published_at:
              type: string
            retrieved_at:
              type: string
            basis:
              type: string
          required:
            - values
            - source
            - source_url
            - published_at
            - retrieved_at
            - basis
        fundamentals:
          type: array
          items:
            type: object
            properties:
              series_id:
                type: string
              frequency:
                type: string
              source_url:
                type: string
                nullable: true
              source_publication_date:
                type: string
                nullable: true
              observation_status:
                type: string
              currency:
                type: string
                nullable: true
              transform:
                type: string
                nullable: true
              indicator_code:
                type: string
              label:
                type: string
              value:
                type: number
                nullable: true
              units:
                type: string
              period:
                type: string
                nullable: true
              vintage:
                type: string
                nullable: true
              ingested_at:
                type: string
                nullable: true
              source:
                type: string
              source_dataset:
                type: string
              attribution:
                type: string
              license_code:
                type: string
            required:
              - indicator_code
              - label
              - value
              - units
              - period
              - vintage
              - ingested_at
              - source
              - source_dataset
              - attribution
              - license_code
          nullable: true
        facilities:
          type: object
          properties:
            by_type:
              type: array
              items:
                type: object
                properties:
                  facility_type:
                    type: string
                  facility_count:
                    type: number
                    description: >-
                      Canonical sites using the facilities directory site
                      identity.
                  unit_count:
                    type: number
                    description: >-
                      Distinct current registry units represented by these
                      sites.
                required:
                  - facility_type
                  - facility_count
                  - unit_count
            counting_basis:
              type: string
            evidence_url:
              type: string
          required:
            - by_type
            - counting_basis
            - evidence_url
          nullable: true
        people_and_offices:
          type: object
          additionalProperties: {}
          nullable: true
        section_availability:
          type: object
          additionalProperties:
            type: object
            properties:
              status:
                type: string
                enum:
                  - available
                  - unavailable
                  - withheld
              measured_at:
                type: string
                nullable: true
            required:
              - status
              - measured_at
      required:
        - iso3
        - name
        - activity
        - hourly
        - edges
        - currencies
        - fundamentals
        - facilities
        - people_and_offices
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: gdelt_sk_...
      description: 'GDELT Cloud API key. Send as `Authorization: Bearer gdelt_sk_...`.'

````