v1.9.0 - Global Macro Sentiment Indices (GMSI) Endpoints

Five new endpoints give you access to the Global Macro Sentiment Indices (GMSI) dataset — hourly country-level sentiment aggregates across 70 macro topics, built from a dedicated country-matched article pipeline with separate directional and semantic sentiment models.

Added

Topic Taxonomy

• GET /v1/headlines/topics/gmsi — Returns the full list of GMSI topics. Topics are consistent across all countries so this endpoint requires no path parameters. Use the returned topic names as the topic value on the feed and index endpoints.

  The 70 topics span 8 top-level categories:

  Category	Example topics
  Economic Data	Inflation-Food, Labour Market-Employment, Production Growth-Industrial
  Monetary Policy	Policy Tools-Interest Rates, Policy Outlook, Independence
  Fiscal Policy	Fiscal Stance, Public Debt, Fiscal Instruments-Taxation
  Financial Markets	Benchmark Equity Indices, Financial Stability-Banking Stress, Market Stress
  Geopolitics	Wars, Tension, Supply Chain Risk-Energy
  Trade	Tariffs and Sanctions, Trade Activity, Foreign Investment
  Politics	Elections, Policy Reform & Legislation, Governance/Corruption
  Exogenous Shocks	Public Health, Natural Disasters, Weather-Extreme Heat

News Feed — Headlines

• GET /v1/headlines/feed/live/gmsi/{country} — Latest GMSI headlines for a country over the past 24 hours. Each record carries per-topic directional and semantic sentiment scores.

  Path parameter:

  • country — ISO-2 country code. Use GET /v1/countries to browse all supported countries, or GET /v1/countries/search to find a specific country by name. 97 countries are supported.

  Query parameters:

  • topic — Required. Single topic name (use /topics/gmsi for available options)
  • match_type — COMBINED (default), DOMESTIC, or INTERNATIONAL
  • limit — Records per page. Default 100, maximum 1000

  Response shape:

  JSON

  [
    {
      "publication_time": "2026-05-21T13:00:00",
      "topic_probability": 0.91,
      "directional_positive": 0.70,
      "directional_neutral": 0.20,
      "directional_negative": 0.10,
      "directional_score": 0.60,
      "semantic_sentiment_positive": 0.65,
      "semantic_sentiment_neutral": 0.25,
      "semantic_sentiment_negative": 0.10,
      "semantic_sentiment_score": 0.55
    }
  ]

• GET /v1/headlines/feed/historical/gmsi/{country} — Paginated historical GMSI headlines for a country. Accepts the same filters as the live endpoint plus date range and pagination controls.

  Additional query parameters:

  • start_date — Start of the query window in YYYY-MM-DD format (required)
  • end_date — Optional end of the query window in YYYY-MM-DD format
  • next_token — Pagination cursor returned by the previous response. Pass this to fetch the next page

  Response shape (PaginatedGmsiHeadlinesResponse):

  JSON

  {
    "data": [ ... ],
    "limit": 100,
    "next_token": "<opaque_token>",
    "has_more": true
  }

Indices — Macro Headline Sentiment

• GET /v1/headlines/index/gmsi/live/{country} — Latest hourly GMSI sentiment index values for a country over the past 24 hours. Each data point aggregates headline sentiment for a single topic–hour bucket.

  Query parameters:

  • topic — Required. Single topic name (use /topics/gmsi for available options)
  • sentiment_type — directional (default) or semantic_sentiment
  • index_type — COMBINED (default), DOMESTIC, or INTERNATIONAL

  Response shape:

  JSON

  [
    {
      "publication_time": "2026-05-21T12:00:00",
      "headline_count": 7,
      "sentiment_sum": 2.4,
      "sentiment_abs_sum": 3.1,
      "sentiment_std": 0.38
    }
  ]

• GET /v1/headlines/index/gmsi/historical/{country} — Paginated historical hourly GMSI index data. Accepts the same filters as the live index endpoint plus date range and pagination controls.

  Additional query parameters:

  • start_date — Start of the query window in YYYY-MM-DD format (required)
  • end_date — Optional end of the query window
  • limit — Records per page. Default 100, maximum 1000
  • next_token — Keyset pagination cursor from the previous response

  Response shape (PaginatedGmsiIndexResponse):

  JSON

  {
    "data": [ ... ],
    "limit": 100,
    "next_token": "<opaque_token>",
    "has_more": true
  }

  Pagination: Pass the next_token from any response as next_token on the next request to advance through the result set. When has_more is false and next_token is null you have reached the end of the available data.

Country Discovery

GMSI endpoints use ISO-2 country codes as path parameters. Use GET /v1/countries to browse all supported countries, or GET /v1/countries/search to find a specific country by name. Both endpoints return an id field — pass that value as the {country} path parameter. 97 countries are currently supported across all major economies.

• GET /v1/countries — Returns a paginated list of all supported countries in alphabetical order. Use this to browse the full set of available country codes and names.

  Query parameters:

  • limit — Countries per page. Default 10, maximum 100
  • offset — Starting position for the current page. Default 0

  Response shape (PaginatedCountryListResponse):

  JSON

  {
    "countries": [
      {
        "id": "AU",
        "name": "Australia",
        "official_name": "Commonwealth of Australia",
        "numeric_id": 36,
        "languages": "English",
        "currency": "AUD",
        "population": 25690000
      }
    ],
    "total": 97,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }