openapi: 3.1.0
info:
  title: Moody's Data Buffet Baskets Search API
  version: 1.0.0
  description: The Moody's Analytics Data Buffet API provides programmatic access to international and subnational economic, demographic, and financial time series data and forecasts. It enables retrieval of individual series or baskets of data, supports frequency conversion, mathematical transformations, date range filtering, and vintage/versioning selection. Code samples are available in C#, Java, Python, and R.
  contact:
    name: Moody's Analytics
    url: https://www.economy.com/products/tools/data-buffet
  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/data/v1
  description: Moody's Analytics Data Buffet production server
security:
- oauth2: []
tags:
- name: Search
  description: Operations for searching available datasets and series
paths:
  /search:
    get:
      operationId: searchSeries
      summary: Moody's Search for Available Series
      description: Searches the Data Buffet repository for available series matching the specified criteria. Supports filtering by keyword, geography, source, and category.
      tags:
      - Search
      parameters:
      - name: query
        in: query
        description: Search query string to match against series names, descriptions, mnemonics, and metadata.
        required: true
        schema:
          type: string
      - name: geography
        in: query
        description: Filter results by geographic area code (e.g., US for United States, GB for United Kingdom, CN for China).
        required: false
        schema:
          type: string
      - name: source
        in: query
        description: Filter results by data source identifier (e.g., BLS, BEA, IMF, Eurostat).
        required: false
        schema:
          type: string
      - name: category
        in: query
        description: Filter results by data category (e.g., GDP, Employment, Inflation, Housing).
        required: false
        schema:
          type: string
      - name: offset
        in: query
        description: The number of results to skip for pagination.
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - name: limit
        in: query
        description: The maximum number of results to return per page.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      responses:
        '200':
          description: Successfully retrieved search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or expired token
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SearchResults:
      type: object
      description: Paginated search results for series queries.
      required:
      - totalCount
      - results
      properties:
        totalCount:
          type: integer
          description: Total number of matching series across all pages.
          example: 10
        offset:
          type: integer
          description: The current pagination offset.
          example: 10
        limit:
          type: integer
          description: The maximum results per page.
          example: 10
        results:
          type: array
          description: Array of matching series metadata.
          items:
            $ref: '#/components/schemas/SeriesSummary'
          example: []
    SeriesSummary:
      type: object
      description: Summary metadata for a series returned in search results.
      required:
      - mnemonic
      - description
      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: Native frequency of the series.
          example: example_value
        source:
          type: string
          description: The original data source.
          example: example_value
        geography:
          type: string
          description: Geographic area covered by the series.
          example: example_value
        category:
          type: string
          description: Data category classification.
          example: example_value
        startDate:
          type: string
          format: date
          description: Earliest available observation date.
          example: '2026-01-15'
        endDate:
          type: string
          format: date
          description: Latest available observation or forecast date.
          example: '2026-01-15'
        hasForecast:
          type: boolean
          description: Whether the series includes forecast data from Moody's Analytics models.
          example: true
    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
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 client credentials flow for authenticating API requests. Obtain client_id and client_secret from your Moody's Analytics account.
      flows:
        clientCredentials:
          tokenUrl: https://api.economy.com/data/v1/oauth2/token
          scopes: {}
externalDocs:
  description: Moody's Data Buffet API Documentation
  url: https://api.economy.com/data/v1/swagger