openapi: 3.0.1
info:
  version: 1.0.0
  title: Authorization Tokens Accounts Research Ratings Most Recent and Historical API
  description: 'Use the `oauth` endpoint to generate the secure, time-limited JSON Web Tokens (JWTs) used to authorize access to APIs and components.</br></br>

    To request a token, click Authorize and enter the following credentials:


    * Username - Your Client ID.

    * Password - Your Client Secret.'
servers:
- url: https://www.us-api.morningstar.com/token
  description: PROD US
- url: https://www.emea-api.morningstar.com/token
  description: PROD EMEA
- url: https://www.apac-api.morningstar.com/token
  description: PROD APAC
security:
- BasicAuth: []
tags:
- name: Research Ratings Most Recent and Historical
paths:
  /direct-web-services/v1/investments/{id}/equity-research-ratings-most-recent-and-historical:
    get:
      summary: Get Research Ratings Most Recent view
      parameters:
      - name: id
        in: path
        description: "\nSpecifies the investment to query. \nMorningstar Performance ID is the default identifer for the API. Use the Universe API to retrieve Performance IDs for investments in your entitled universe."
        required: true
        schema:
          type: string
          example: 0P00000046
        examples:
          performanceId:
            summary: Morningstar Performance ID
            value: 0P00000046
          isin:
            summary: ISIN
            value: US0042391096
      - name: idType
        in: query
        description: 'Specifies the type of the value passed in the `id` parameter.

          Morningstar Performance ID is the default identifer for the API. Use the Universe API to retrieve Performance IDs for investments in your entitled universe.'
        schema:
          enum:
          - performanceId
          - isin
          - securityId
          - cusip
          - tradingSymbol
          - fundCode
          - msid
          type: string
          default: performanceId
      - name: baseCurrency
        in: query
        description: Base currency to use for investment lookup. Accepts 3‑character ISO 4217 currency codes.
        schema:
          type: string
        examples:
          baseCurrencyExample1:
            summary: US Dollar
            value: USD
          baseCurrencyExample2:
            summary: Swiss Franc
            value: CHF
      - name: domicile
        in: query
        description: Domicile to use for investment lookup. Accepts 3-character ISO 3166-1 country codes.
        schema:
          type: string
        examples:
          domicileExample1:
            summary: CAN (Canada)
            value: CAN
          domicileExample2:
            summary: JPN (Japan)
            value: JPN
          domicileExample3:
            summary: USE (United States)
            value: USA
      - name: exchangeCountry
        in: query
        description: Exchange country to use for investment lookup. Accepts 3-character ISO 3166-1 country codes.
        schema:
          type: string
        examples:
          exchangeCountryExample1:
            summary: CAN (Canada)
            value: CAN
          exchangeCountryExample2:
            summary: JPN (Japan)
            value: JPN
          exchangeCountryExample3:
            summary: USA (USA)
            value: USA
      - name: exchangeId
        in: query
        description: Exchange identifier to use for investment lookup.
        schema:
          type: string
          externalDocs:
            description: List of exchange IDs.
            url: https://developer.morningstar.com/content/hidden-from-navigation/DwsIdLookUpExchangeIds.xlsx
        examples:
          exchangeIdExample1:
            summary: NASDAQ - ALL Markets (NAS)
            value: EX$$$$XNAS
          exchangeIdExample2:
            summary: London Stock Exchange (LSE)
            value: EX$$$$XLON
      - name: startDate
        in: query
        schema:
          type: string
          format: yyyy-MM-dd
        description: Time series start date. Accepts `yyyy-MM-dd`.
        examples:
          startDateExample1:
            summary: Example 1
            value: '2025-06-01'
          startDateExample2:
            summary: Example 2
            value: '2025-06-30'
      - name: endDate
        in: query
        schema:
          type: string
          format: yyyy-MM-dd
        description: Time series end date. Accepts `yyyy-MM-dd`.
        examples:
          endDateExample1:
            summary: Example 1
            value: '2025-12-01'
          endDateExample2:
            summary: Example 2
            value: '2025-12-31'
      description: Most recent data supported.
      operationId: getEquityResearchRatingsMostRecentAndHistoricalDataset
      tags:
      - Research Ratings Most Recent and Historical
      responses:
        '200':
          $ref: '#/components/responses/ResponseEquityResearchRatingsMostRecentAndHistorical'
        '400':
          $ref: '#/components/responses/ResponseBadRequest'
        '500':
          $ref: '#/components/responses/ResponseInternalServerError'
      x-cpqId: 176
components:
  schemas:
    OutputMetadataMessages:
      type: object
      properties:
        type:
          type: string
          nullable: true
        code:
          type: string
          nullable: true
        investments:
          type: array
          items:
            $ref: '#/components/schemas/OutputInvalidInvestments'
          nullable: true
        message:
          type: string
          nullable: true
      additionalProperties: false
      title: OutputMetadataMessages
    CodeMappingString:
      type: object
      properties:
        value:
          type: string
          nullable: true
        code:
          type: string
          nullable: true
      additionalProperties: false
      title: CodeMappingString
    OutputEquityResearchRatingsMostRecentAndHistorical:
      type: object
      properties:
        analysisDate:
          type: string
          description: ''
          nullable: true
        analystName:
          type: string
          description: ''
          nullable: true
        stockTypeMonthly:
          $ref: '#/components/schemas/CodeMappingString'
        starRatingDaily:
          $ref: '#/components/schemas/CodeMappingInt'
        fairValueUncertaintyDaily:
          type: string
          description: ''
          nullable: true
        costOfEquityDaily:
          type: number
          description: ''
          format: double
          nullable: true
        economicMoatDaily:
          type: string
          description: ''
          nullable: true
        fairValueDaily:
          type: number
          description: ''
          format: double
          nullable: true
        considerBuyingDaily:
          type: number
          description: ''
          format: double
          nullable: true
        considerSellingDaily:
          type: number
          description: ''
          format: double
          nullable: true
        stockCapitalAllocationDaily:
          type: string
          description: ''
          nullable: true
        starRatingMonthly:
          $ref: '#/components/schemas/CodeMappingInt'
        fairValueUncertaintyMonthly:
          type: string
          description: ''
          nullable: true
        costOfEquityMonthly:
          type: number
          description: ''
          format: double
          nullable: true
        economicMoatMonthly:
          type: string
          description: ''
          nullable: true
        fairValueMonthly:
          type: number
          description: ''
          format: double
          nullable: true
        considerBuyingMonthly:
          type: number
          description: ''
          format: double
          nullable: true
        considerSellingMonthly:
          type: number
          description: ''
          format: double
          nullable: true
        stockCapitalAllocationMonthly:
          type: string
          description: ''
          nullable: true
        economicMoat:
          $ref: '#/components/schemas/CodeMappingString'
        morningstarFairValueStatus:
          $ref: '#/components/schemas/CodeMappingString'
        businessRisk:
          $ref: '#/components/schemas/CodeMappingString'
        morningstarFairValuePerShare:
          type: number
          description: ''
          format: double
          nullable: true
        considerSell:
          type: number
          description: ''
          format: double
          nullable: true
        considerBuy:
          type: number
          description: ''
          format: double
          nullable: true
        dateMorningstarRating:
          type: string
          description: ''
          nullable: true
      additionalProperties: false
      title: OutputEquityResearchRatingsMostRecentAndHistorical
    OutputErrorDetails:
      type: object
      properties:
        statusCode:
          type: integer
          description: Status Code
          format: int32
        errorCode:
          type: string
          description: Custom error code
          nullable: true
        message:
          type: string
          description: Message
          nullable: true
        requestId:
          type: string
          description: RequestId
          nullable: true
      additionalProperties: false
      description: Error details
      title: OutputErrorDetails
    OutputInvalidInvestments:
      type: object
      properties:
        id:
          type: string
          nullable: true
        idType:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        datapointId:
          type: array
          items:
            type: string
          nullable: true
        errorCode:
          type: string
          nullable: true
        performanceId:
          type: string
          description: Performance ID (if not passed in request).
          nullable: true
        companyId:
          type: string
          description: Company ID (if not passed in request).
          nullable: true
        baseCurrency:
          type: string
          description: Input base currency used to look up Investment identifier
          nullable: true
        domicile:
          type: string
          description: Input domicile used to look up Investment identifier.
          nullable: true
        exchangeCountry:
          type: string
          description: Input exchange country used to look up Investment identifier.
          nullable: true
        exchangeId:
          type: string
          description: Input exchange id used to look up Investment identifier.
          nullable: true
      additionalProperties: false
      title: OutputInvalidInvestments
    OutputIdentifiers:
      type: object
      properties:
        performanceId:
          type: string
          nullable: true
        securityId:
          type: string
          nullable: true
        cusip:
          type: string
          nullable: true
        isin:
          type: string
          nullable: true
        sedol:
          type: string
          nullable: true
        tradingSymbol:
          type: string
          nullable: true
        fundCode:
          type: string
          nullable: true
        msid:
          type: string
          nullable: true
        ticker:
          type: string
          nullable: true
      additionalProperties: false
      title: OutputIdentifiers
    OutputMetadata:
      type: object
      properties:
        requestId:
          type: string
          nullable: true
        time:
          type: string
          format: date-time
          readOnly: true
        portfolioDate:
          type: string
          nullable: true
        portfolioCurrency:
          type: string
          nullable: true
        messages:
          type: array
          items:
            $ref: '#/components/schemas/OutputMetadataMessages'
          nullable: true
      additionalProperties: false
      title: OutputMetadata
    CodeMappingInt:
      type: object
      properties:
        value:
          type: string
          nullable: true
        code:
          type: integer
          format: int32
          nullable: true
      additionalProperties: false
      title: CodeMappingInt
  responses:
    ResponseBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OutputErrorDetails'
    ResponseInternalServerError:
      description: Internal Server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OutputErrorDetails'
    ResponseEquityResearchRatingsMostRecentAndHistorical:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              equityResearchRatingsMostRecentAndHistorical:
                $ref: '#/components/schemas/OutputEquityResearchRatingsMostRecentAndHistorical'
              identifiers:
                $ref: '#/components/schemas/OutputIdentifiers'
              metadata:
                $ref: '#/components/schemas/OutputMetadata'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic