openapi: 3.0.1
info:
  title: Trading Economics API
  description: >-
    REST API for Trading Economics economic data covering 196 countries -
    economic indicators (interest rates, inflation, GDP, unemployment, and
    15,000+ other series), the economic calendar, proprietary macro forecasts,
    full historical time series, live market quotes, and company financials.
    Authenticate with an API client key passed as the `c` query parameter
    (format `key:secret`) or as an `Authorization` header. Output defaults to
    JSON and can be switched with `f=json|csv|html`. Live streaming is a
    separate WebSocket surface at wss://stream.tradingeconomics.com described
    in the companion AsyncAPI document.
  termsOfService: https://tradingeconomics.com/terms-of-service.aspx
  contact:
    name: Trading Economics
    url: https://tradingeconomics.com/contact.aspx
  version: '1.0'
externalDocs:
  description: Trading Economics API Documentation
  url: https://docs.tradingeconomics.com
servers:
  - url: https://api.tradingeconomics.com
security:
  - clientKeyQuery: []
  - clientKeyHeader: []
paths:
  /country/{country}:
    get:
      operationId: getIndicatorsByCountry
      tags:
        - Indicators
      summary: Latest indicator values for one or more countries.
      description: >-
        Returns a snapshot of the latest values for all economic indicators for
        the given country (or comma-separated countries), including interest
        rates, inflation, GDP, and unemployment. Optionally filter to a
        category group such as `gdp` with the `group` parameter.
      parameters:
        - name: country
          in: path
          required: true
          description: Country name, or comma-separated list (e.g. `mexico,sweden`).
          schema:
            type: string
          example: mexico
        - name: group
          in: query
          required: false
          description: Filter results to a category group (e.g. `gdp`).
          schema:
            type: string
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Indicator'
  /country/all/{indicator}:
    get:
      operationId: getCountriesByIndicator
      tags:
        - Indicators
      summary: Latest values of one indicator across all countries.
      description: >-
        Returns the latest value of a single indicator - such as `interest
        rate`, `inflation rate`, or `gdp` - for every country covered,
        supporting cross-country comparison of macroeconomic series.
      parameters:
        - name: indicator
          in: path
          required: true
          description: Indicator name (e.g. `interest rate`, `gdp`).
          schema:
            type: string
          example: interest rate
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Indicator'
  /country/ticker/{ticker}:
    get:
      operationId: getIndicatorByTicker
      tags:
        - Indicators
      summary: Latest indicator value by Trading Economics ticker.
      parameters:
        - name: ticker
          in: path
          required: true
          description: Trading Economics indicator ticker (e.g. `usurtot`).
          schema:
            type: string
          example: usurtot
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Indicator'
  /credit-ratings:
    get:
      operationId: getCreditRatings
      tags:
        - Indicators
      summary: Sovereign credit ratings for all countries.
      parameters:
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CreditRating'
  /credit-ratings/country/{country}:
    get:
      operationId: getCreditRatingsByCountry
      tags:
        - Indicators
      summary: Sovereign credit ratings for one or more countries.
      parameters:
        - name: country
          in: path
          required: true
          description: Country name, or comma-separated list (e.g. `mexico,sweden`).
          schema:
            type: string
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CreditRating'
  /calendar:
    get:
      operationId: getCalendar
      tags:
        - Economic Calendar
      summary: Upcoming and recent economic calendar events.
      description: >-
        Returns scheduled economic events - central bank interest rate
        decisions, CPI, GDP, employment releases, and more - with actual,
        previous, consensus forecast, and Trading Economics forecast values.
        Filter by importance (1=low, 2=medium, 3=high). Limited to 1,000 rows
        per request.
      parameters:
        - name: importance
          in: query
          required: false
          description: Event importance filter (1=low, 2=medium, 3=high).
          schema:
            type: integer
            enum: [1, 2, 3]
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalendarEvent'
  /calendar/country/{countries}/{startDate}/{endDate}:
    get:
      operationId: getCalendarByCountryAndDate
      tags:
        - Economic Calendar
      summary: Calendar events by country and date range.
      description: >-
        Returns calendar events for the given countries (use `All` for every
        country) between two dates, optionally filtered by importance.
      parameters:
        - name: countries
          in: path
          required: true
          description: Country name(s) comma-separated, or `All`.
          schema:
            type: string
          example: All
        - name: startDate
          in: path
          required: true
          schema:
            type: string
            format: date
          example: '2026-07-01'
        - name: endDate
          in: path
          required: true
          schema:
            type: string
            format: date
          example: '2026-07-31'
        - name: importance
          in: query
          required: false
          schema:
            type: integer
            enum: [1, 2, 3]
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalendarEvent'
  /calendar/events/country/{countries}:
    get:
      operationId: getCalendarEventsByCountry
      tags:
        - Economic Calendar
      summary: Calendar event types available for one or more countries.
      parameters:
        - name: countries
          in: path
          required: true
          description: Country name, or comma-separated list (e.g. `china,canada`).
          schema:
            type: string
          example: china
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalendarEvent'
  /calendar/calendarid/{ids}:
    get:
      operationId: getCalendarEventsById
      tags:
        - Economic Calendar
      summary: Calendar events by calendar ID.
      parameters:
        - name: ids
          in: path
          required: true
          description: Comma-separated calendar IDs (e.g. `174108,160025,160030`).
          schema:
            type: string
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalendarEvent'
  /calendar/updates:
    get:
      operationId: getCalendarUpdates
      tags:
        - Economic Calendar
      summary: Recently updated calendar events.
      parameters:
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CalendarEvent'
  /markets/commodities:
    get:
      operationId: getMarketsCommodities
      tags:
        - Markets
      summary: Current quotes for commodities.
      parameters:
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketQuote'
  /markets/currency:
    get:
      operationId: getMarketsCurrencies
      tags:
        - Markets
      summary: Current quotes for currency pairs.
      parameters:
        - name: cross
          in: query
          required: false
          description: Filter crosses of a base currency (e.g. `EUR`).
          schema:
            type: string
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketQuote'
  /markets/index:
    get:
      operationId: getMarketsIndexes
      tags:
        - Markets
      summary: Current quotes for stock market indexes.
      parameters:
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketQuote'
  /markets/crypto:
    get:
      operationId: getMarketsCrypto
      tags:
        - Markets
      summary: Current quotes for cryptocurrencies.
      parameters:
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketQuote'
  /markets/bond:
    get:
      operationId: getMarketsBonds
      tags:
        - Markets
      summary: Current government bond yields.
      description: >-
        Returns government bond yields. Filter by maturity with `type` (1M,
        3M, 6M, 52W, 2Y, 3Y, 5Y, 7Y, 10Y, 15Y, 20Y, 30Y) and by country with
        `country` - the market-side complement to policy interest rate series.
      parameters:
        - name: type
          in: query
          required: false
          description: Bond maturity (e.g. `10Y`).
          schema:
            type: string
            enum: [1M, 3M, 6M, 52W, 2Y, 3Y, 5Y, 7Y, 10Y, 15Y, 20Y, 30Y]
        - name: country
          in: query
          required: false
          description: Filter by country (e.g. `france`).
          schema:
            type: string
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketQuote'
  /markets/symbol/{symbols}:
    get:
      operationId: getMarketsBySymbol
      tags:
        - Markets
      summary: Current quotes for specific market symbols.
      parameters:
        - name: symbols
          in: path
          required: true
          description: Comma-separated market symbols (e.g. `aapl:us,indu:ind`).
          schema:
            type: string
          example: aapl:us
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketQuote'
  /markets/historical/{symbols}:
    get:
      operationId: getMarketsHistorical
      tags:
        - Markets
      summary: Daily historical prices for market symbols.
      parameters:
        - name: symbols
          in: path
          required: true
          description: Comma-separated market symbols.
          schema:
            type: string
        - name: d1
          in: query
          required: false
          description: Start date (yyyy-mm-dd).
          schema:
            type: string
            format: date
        - name: d2
          in: query
          required: false
          description: End date (yyyy-mm-dd).
          schema:
            type: string
            format: date
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketHistoricalPrice'
  /markets/intraday/{symbols}:
    get:
      operationId: getMarketsIntraday
      tags:
        - Markets
      summary: Intraday prices for market symbols.
      parameters:
        - name: symbols
          in: path
          required: true
          description: Comma-separated market symbols.
          schema:
            type: string
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketHistoricalPrice'
  /markets/search/{term}:
    get:
      operationId: searchMarkets
      tags:
        - Markets
      summary: Search market instruments by term.
      parameters:
        - name: term
          in: path
          required: true
          schema:
            type: string
        - name: category
          in: query
          required: false
          description: Restrict search to a category (e.g. `index`, `bond`).
          schema:
            type: string
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MarketQuote'
  /forecast/country/{countries}:
    get:
      operationId: getForecastsByCountry
      tags:
        - Forecasts
      summary: Indicator forecasts for one or more countries.
      description: >-
        Returns multi-quarter forecasts for all economic indicators of the
        given countries, built with the Trading Economics proprietary global
        macro model and analyst expectations.
      parameters:
        - name: countries
          in: path
          required: true
          description: Country name, or comma-separated list (e.g. `mexico,sweden`).
          schema:
            type: string
          example: mexico
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Forecast'
  /forecast/indicator/{indicators}:
    get:
      operationId: getForecastsByIndicator
      tags:
        - Forecasts
      summary: Forecasts for one or more indicators across countries.
      parameters:
        - name: indicators
          in: path
          required: true
          description: Indicator name(s), comma-separated (e.g. `interest rate,gdp`).
          schema:
            type: string
          example: interest rate
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Forecast'
  /forecast/country/{countries}/indicator/{indicators}:
    get:
      operationId: getForecastsByCountryAndIndicator
      tags:
        - Forecasts
      summary: Forecasts by country and indicator.
      parameters:
        - name: countries
          in: path
          required: true
          schema:
            type: string
          example: mexico,sweden
        - name: indicators
          in: path
          required: true
          schema:
            type: string
          example: gdp,population
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Forecast'
  /forecast/ticker/{tickers}:
    get:
      operationId: getForecastsByTicker
      tags:
        - Forecasts
      summary: Forecasts by Trading Economics ticker.
      parameters:
        - name: tickers
          in: path
          required: true
          description: Comma-separated tickers (e.g. `usurtot,wgdpchin`).
          schema:
            type: string
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Forecast'
  /historical/country/{countries}/indicator/{indicators}:
    get:
      operationId: getHistoricalByCountryAndIndicator
      tags:
        - Historical
      summary: Historical time series by country and indicator.
      description: >-
        Returns the historical time series for the given countries and
        indicators (both comma-separatable). Limited to 10,000 rows per
        request.
      parameters:
        - name: countries
          in: path
          required: true
          schema:
            type: string
          example: mexico
        - name: indicators
          in: path
          required: true
          schema:
            type: string
          example: gdp
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoricalValue'
  /historical/country/{countries}/indicator/{indicators}/{startDate}/{endDate}:
    get:
      operationId: getHistoricalByCountryIndicatorAndDates
      tags:
        - Historical
      summary: Historical time series by country, indicator, and date range.
      parameters:
        - name: countries
          in: path
          required: true
          schema:
            type: string
          example: mexico,sweden
        - name: indicators
          in: path
          required: true
          schema:
            type: string
          example: gdp,population
        - name: startDate
          in: path
          required: true
          schema:
            type: string
            format: date
          example: '2015-01-01'
        - name: endDate
          in: path
          required: true
          schema:
            type: string
            format: date
          example: '2015-12-31'
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoricalValue'
  /historical/ticker/{ticker}/{startDate}:
    get:
      operationId: getHistoricalByTicker
      tags:
        - Historical
      summary: Historical time series by ticker from a start date.
      parameters:
        - name: ticker
          in: path
          required: true
          schema:
            type: string
          example: usurtot
        - name: startDate
          in: path
          required: true
          schema:
            type: string
            format: date
          example: '2015-03-01'
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoricalValue'
  /historical/latest:
    get:
      operationId: getHistoricalLatest
      tags:
        - Historical
      summary: Recently released or revised indicator values.
      parameters:
        - name: country
          in: query
          required: false
          schema:
            type: string
        - name: date
          in: query
          required: false
          schema:
            type: string
            format: date
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoricalValue'
  /historical/updates:
    get:
      operationId: getHistoricalUpdates
      tags:
        - Historical
      summary: Recently updated historical records.
      parameters:
        - name: d1
          in: query
          required: false
          description: Start date filter (yyyy-mm-dd).
          schema:
            type: string
            format: date
        - name: d2
          in: query
          required: false
          description: End date filter (yyyy-mm-dd).
          schema:
            type: string
            format: date
        - name: lu
          in: query
          required: false
          description: Last-update date filter (yyyy-mm-dd).
          schema:
            type: string
            format: date
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoricalValue'
  /financials/category/{category}:
    get:
      operationId: getFinancialsByCategory
      tags:
        - Financials
      summary: Company financials snapshot by category.
      parameters:
        - name: category
          in: path
          required: true
          description: Financial category (e.g. `assets`).
          schema:
            type: string
          example: assets
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Financial'
  /financials/symbol/{symbol}:
    get:
      operationId: getFinancialsBySymbol
      tags:
        - Financials
      summary: Company financials snapshot by stock symbol.
      parameters:
        - name: symbol
          in: path
          required: true
          description: Stock symbol (e.g. `aapl:us`).
          schema:
            type: string
          example: aapl:us
        - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Financial'
components:
  parameters:
    format:
      name: f
      in: query
      required: false
      description: Output format. JSON is the default for most endpoints.
      schema:
        type: string
        enum: [json, csv, html]
  securitySchemes:
    clientKeyQuery:
      type: apiKey
      in: query
      name: c
      description: >-
        API client credentials in `key:secret` format passed as the `c` query
        parameter. Obtain a key by subscribing to a plan at
        developer.tradingeconomics.com.
    clientKeyHeader:
      type: apiKey
      in: header
      name: Authorization
      description: API client credentials passed in the Authorization header.
  schemas:
    Indicator:
      type: object
      description: Latest value of an economic indicator for a country.
      properties:
        Country:
          type: string
          example: Mexico
        Category:
          type: string
          example: Interest Rate
        Title:
          type: string
          example: Mexico Interest Rate
        LatestValue:
          type: number
        LatestValueDate:
          type: string
          format: date-time
        PreviousValue:
          type: number
        PreviousValueDate:
          type: string
          format: date-time
        Source:
          type: string
        Unit:
          type: string
          example: percent
        Frequency:
          type: string
          example: Daily
        HistoricalDataSymbol:
          type: string
          example: MXONBR
        CategoryGroup:
          type: string
          example: Money
        LastUpdate:
          type: string
          format: date-time
    CreditRating:
      type: object
      description: Sovereign credit rating assessment for a country.
      properties:
        Country:
          type: string
        TE:
          type: string
          description: Trading Economics credit rating score.
        TE_Outlook:
          type: string
        SP:
          type: string
          description: Standard and Poor's rating.
        SP_Outlook:
          type: string
        Moodys:
          type: string
        Moodys_Outlook:
          type: string
        Fitch:
          type: string
        Fitch_Outlook:
          type: string
    CalendarEvent:
      type: object
      description: A scheduled economic calendar event.
      properties:
        CalendarId:
          type: string
        Date:
          type: string
          format: date-time
        Country:
          type: string
        Category:
          type: string
          example: Interest Rate
        Event:
          type: string
          example: Fed Interest Rate Decision
        Reference:
          type: string
        ReferenceDate:
          type: string
        Actual:
          type: string
        Previous:
          type: string
        Forecast:
          type: string
          description: Average forecast among economists surveyed.
        TEForecast:
          type: string
          description: Trading Economics proprietary forecast.
        Importance:
          type: integer
          description: 1=low, 2=medium, 3=high.
        Ticker:
          type: string
        Unit:
          type: string
        LastUpdate:
          type: string
          format: date-time
    MarketQuote:
      type: object
      description: Current quote for a market instrument.
      properties:
        Symbol:
          type: string
          example: EURUSD:CUR
        Ticker:
          type: string
        Name:
          type: string
        Country:
          type: string
        Date:
          type: string
          format: date-time
        Last:
          type: number
        Group:
          type: string
        DailyChange:
          type: number
        DailyPercentualChange:
          type: number
        WeeklyChange:
          type: number
        MonthlyChange:
          type: number
        YearlyChange:
          type: number
        YTDChange:
          type: number
        yesterday:
          type: number
        lastWeek:
          type: number
        lastMonth:
          type: number
        lastYear:
          type: number
        unit:
          type: string
    MarketHistoricalPrice:
      type: object
      description: Historical or intraday price bar for a market symbol.
      properties:
        Symbol:
          type: string
        Date:
          type: string
          format: date-time
        Open:
          type: number
        High:
          type: number
        Low:
          type: number
        Close:
          type: number
    Forecast:
      type: object
      description: Multi-quarter forecast for an economic indicator.
      properties:
        Country:
          type: string
        Category:
          type: string
          example: Interest Rate
        Title:
          type: string
        LatestValue:
          type: number
        LatestValueDate:
          type: string
          format: date-time
        Forecast1:
          type: number
          description: Forecast for the next quarter.
        Forecast2:
          type: number
        Forecast3:
          type: number
        Forecast4:
          type: number
        ForecastDate1:
          type: string
        ForecastDate2:
          type: string
        ForecastDate3:
          type: string
        ForecastDate4:
          type: string
        HistoricalDataSymbol:
          type: string
    HistoricalValue:
      type: object
      description: One observation in an indicator's historical time series.
      properties:
        Country:
          type: string
        Category:
          type: string
        DateTime:
          type: string
          format: date-time
        Value:
          type: number
        Frequency:
          type: string
        HistoricalDataSymbol:
          type: string
        LastUpdate:
          type: string
          format: date-time
    Financial:
      type: object
      description: Company fundamentals record.
      properties:
        Symbol:
          type: string
          example: AAPL:US
        Name:
          type: string
        Country:
          type: string
        Category:
          type: string
        Sector:
          type: string
        Value:
          type: number
        Unit:
          type: string
        Date:
          type: string
          format: date-time