Moody's Corporation Series API

openapi: 3.1.0
info:
  title: Moody's Analytics Developer Platform Authentication Series API
  version: 1.0.0
  description: Cross-cutting umbrella API surface for the Moody's Analytics developer platform covering authentication (OAuth2 client credentials and HMAC request signing), platform health, product catalog discovery, and a canonical pattern for asynchronous analysis-job execution used across multiple Moody's Analytics product APIs (Data Buffet, Scenario Studio, ImpairmentStudio, AutoCycle, ECCL).
  contact:
    name: Moody's Analytics Developer Support
    email: helpeconomy@moodys.com
    url: https://developer.moodys.com/
  license:
    name: Moody's Analytics Terms of Use
    url: https://www.moodys.com/web/en/us/about/legal/terms-of-use.html
servers:
- url: https://api.economy.com
  description: Moody's Analytics economy.com API gateway
- url: https://api.moodys.com
  description: Moody's Analytics moodys.com API gateway
security:
- oauth2: []
tags:
- name: Series
  description: Operations for retrieving individual and multi-series time series data
paths:
  /series:
    get:
      operationId: getSeries
      summary: Moody's Retrieve a Single Time Series
      description: Returns data for a single economic, demographic, or financial time series identified by its mnemonic. Supports frequency conversion, mathematical transformations, date range filtering, and vintage selection.
      tags:
      - Series
      parameters:
      - $ref: '#/components/parameters/mnemonic'
      - $ref: '#/components/parameters/freq'
      - $ref: '#/components/parameters/trans'
      - $ref: '#/components/parameters/startDate'
      - $ref: '#/components/parameters/endDate'
      - $ref: '#/components/parameters/vintage'
      responses:
        '200':
          description: Successfully retrieved time series data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesResponse'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or expired token
        '404':
          description: Series mnemonic not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /multi-series:
    post:
      operationId: getMultiSeries
      summary: Moody's Retrieve Multiple Time Series
      description: Returns data for up to 25 time series in a single request. Each series can have individual frequency, transformation, date range, and vintage parameters. Useful for efficiently fetching related economic indicators together.
      tags:
      - Series
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiSeriesRequest'
      responses:
        '200':
          description: Successfully retrieved multiple time series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiSeriesResponse'
        '400':
          description: Invalid request or exceeded 25 series limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or expired token
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Error:
      type: object
      description: Standard error response.
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: example_value
        message:
          type: string
          description: Human-readable error message.
          example: example_value
        details:
          type: string
          description: Additional details about the error.
          example: example_value
    Observation:
      type: object
      description: A single time series observation or forecast data point.
      required:
      - date
      - value
      properties:
        date:
          type: string
          format: date
          description: The observation date in YYYY-MM-DD format. For frequencies coarser than daily, represents the period start date.
          example: '2026-01-15'
        value:
          type:
          - number
          - 'null'
          description: The observation value. Null indicates missing or unavailable data for this period.
          example: example_value
        status:
          type: string
          description: Status indicator for the data point.
          enum:
          - History
          - Forecast
          - Preliminary
          example: History
    MultiSeriesResponse:
      type: object
      description: Response containing multiple time series.
      required:
      - series
      properties:
        series:
          type: array
          description: Array of time series responses.
          items:
            $ref: '#/components/schemas/SeriesResponse'
          example: []
    MultiSeriesRequest:
      type: object
      description: Request body for retrieving multiple series simultaneously.
      required:
      - series
      properties:
        series:
          type: array
          description: Array of series requests. Maximum 25 series per request.
          maxItems: 25
          items:
            $ref: '#/components/schemas/SeriesRequest'
          example: []
    SeriesResponse:
      type: object
      description: Response containing a single time series with metadata and observations.
      required:
      - mnemonic
      - description
      - frequency
      - data
      properties:
        mnemonic:
          type: string
          description: The unique series mnemonic identifier.
          example: example_value
        description:
          type: string
          description: Human-readable description of the series.
          example: A sample description.
        frequency:
          type: string
          description: The frequency of the returned data.
          enum:
          - Annual
          - Quarterly
          - Monthly
          - Weekly
          - Daily
          example: Annual
        source:
          type: string
          description: The original data source (e.g., BLS, BEA, IMF).
          example: example_value
        geography:
          type: string
          description: The geographic area the series covers.
          example: example_value
        units:
          type: string
          description: The unit of measurement for the series values (e.g., Billions of Chained 2017 Dollars, Thousands of Persons, Index).
          example: example_value
        transformation:
          type: string
          description: The transformation applied to the data, if any.
          example: example_value
        startDate:
          type: string
          format: date
          description: The start date of the returned data range.
          example: '2026-01-15'
        endDate:
          type: string
          format: date
          description: The end date of the returned data range.
          example: '2026-01-15'
        vintage:
          type: string
          format: date
          description: The vintage date of the returned data.
          example: '2026-01-15'
        lastUpdated:
          type: string
          format: date-time
          description: When the series was last updated in the repository.
          example: '2026-01-15T10:30:00Z'
        isForecast:
          type: boolean
          description: Whether the series contains forecast data from Moody's Analytics models.
          example: true
        data:
          type: array
          description: Array of date-value pairs representing the time series observations and/or forecasts.
          items:
            $ref: '#/components/schemas/Observation'
          example: []
    SeriesRequest:
      type: object
      description: A single series request within a multi-series call.
      required:
      - mnemonic
      properties:
        mnemonic:
          type: string
          description: The unique series mnemonic identifier.
          example: example_value
        freq:
          type: string
          description: Desired output frequency.
          enum:
          - A
          - Q
          - M
          - W
          - D
          example: A
        trans:
          type: string
          description: Mathematical transformation to apply.
          enum:
          - Level
          - SimpleDifference
          - PercentChange
          - AnnualizedGrowth
          - YearOverYearPercentChange
          - CompoundAnnualGrowthRate
          example: Level
        startDate:
          type: string
          format: date
          description: Start date for the data range.
          example: '2026-01-15'
        endDate:
          type: string
          format: date
          description: End date for the data range.
          example: '2026-01-15'
        vintage:
          type: string
          format: date
          description: Vintage date for historical data revisions.
          example: '2026-01-15'
  parameters:
    mnemonic:
      name: mnemonic
      in: query
      description: The unique series mnemonic identifier. Mnemonics follow the Data Buffet naming convention, e.g., FGDP_US for US GDP or EMPLPAY.IUSA for US total nonfarm payrolls.
      required: true
      schema:
        type: string
      examples:
        usGdp:
          summary: US Gross Domestic Product
          value: FGDP_US
        usPayrolls:
          summary: US Total Nonfarm Payrolls
          value: EMPLPAY.IUSA
    vintage:
      name: vintage
      in: query
      description: The vintage date for accessing historical data revisions in YYYY-MM-DD format. If omitted, returns the latest vintage.
      required: false
      schema:
        type: string
        format: date
    endDate:
      name: endDate
      in: query
      description: The end date for the data range in YYYY-MM-DD format. If omitted, returns data through the latest available observation or forecast.
      required: false
      schema:
        type: string
        format: date
    freq:
      name: freq
      in: query
      description: The desired output frequency for the series. When specified, frequency conversion is applied. For example, converting quarterly GDP to annual.
      required: false
      schema:
        type: string
        enum:
        - A
        - Q
        - M
        - W
        - D
    trans:
      name: trans
      in: query
      description: The mathematical transformation to apply to the series values. Supports common economic transformations.
      required: false
      schema:
        type: string
        enum:
        - Level
        - SimpleDifference
        - PercentChange
        - AnnualizedGrowth
        - YearOverYearPercentChange
        - CompoundAnnualGrowthRate
    startDate:
      name: startDate
      in: query
      description: The start date for the data range in YYYY-MM-DD format. If omitted, returns data from the beginning of the series.
      required: false
      schema:
        type: string
        format: date
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.economy.com/oauth2/token
          scopes:
            read: Read access to entitled Moody's Analytics products
            write: Write access for job submission and basket / order management
    hmac:
      type: apiKey
      in: header
      name: Authorization
      description: HMAC-SHA256 request signing scheme used as an alternative to OAuth2 on legacy Moody's Analytics product APIs (Data Buffet, Scenario Studio).
externalDocs:
  description: Moody's Analytics Developer Portal
  url: https://developer.moodys.com/