Factset Ratings API

openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Ratings API
  description: Allow clients to fetch precalculated Analytics through predeterministic URLs.
  contact:
    name: FactSet Research Systems
    url: https://developer.factset.com/contact
    email: api@factset.com
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 1.0.0
servers:
- url: https://api.factset.com
  description: Production
- url: https://api-sandbox.factset.com
  description: Sandbox
security:
- basicAuth: []
tags:
- name: Ratings
  description: The Consensus and Broker-Level Ratings detail for Buy, Hold, Sell, Overweight, Underweight.
paths:
  /factset-estimates/v2/consensus-ratings:
    get:
      tags:
      - Ratings
      summary: Factset Ratings Consensus Estimates to Fetch Buy, Overweight, Hold, Underweight, and Sell.
      operationId: getConsensusRatings
      description: 'Returns ratings from the FactSet Estimates database for current and historical for an individual security using rolling fiscal dates as of a specific date.

        '
      parameters:
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/startDate'
      - $ref: '#/components/parameters/endDate'
      - $ref: '#/components/parameters/frequency'
      responses:
        '200':
          description: Estimate data items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consensusRatingsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Ratings
      summary: Factset Ratings Consensus Estimates to Fetch Buy, Overweight, Hold, Underweight, and Sell.
      description: 'Returns ratings from the FactSet Estimates database for current and historical for an individual security using rolling fiscal dates as of a specific date.

        '
      operationId: getConsensusRatingsForList
      requestBody:
        required: true
        description: Request object for Estimate Data Items.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/consensusRatingsRequest'
      responses:
        '200':
          description: Estimate data items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/consensusRatingsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /factset-estimates/v2/detail-ratings:
    get:
      tags:
      - Ratings
      summary: Factset Broker Detail Estimates to Fetch Buy, Overweight, Hold, Underweight, and Sell.
      operationId: getDetailRatings
      description: 'Retrieves the Broker Level ratings for the requested Id and date range. Ratings include Buy, Hold, Sell, Overweight, and Underweight.

        <p>The `startDate` and `endDate` parameters controls the range of perspective dates. By default, the service will return the range of estimateDates within the latest company''s reporting period. As you expand the date range, additional full historical reporting periods and all ratings estimateDates per broker will be returned.</p>

        '
      parameters:
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/startDate'
      - $ref: '#/components/parameters/endDate'
      - $ref: '#/components/parameters/includeAll'
      responses:
        '200':
          description: Estimate Ratings data items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/detailRatingsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Ratings
      summary: Factset Broker Detail Estimates to Fetch Buy, Overweight, Hold, Underweight, and Sell.
      description: 'Retrieves the Broker Level ratings for the requested Id and date range. Ratings include Buy, Hold, Sell, Overweight, and Underweight.

        <p>The `startDate` and `endDate` parameters controls the range of perspective dates. By default, the service will return the range of estimateDates within the latest company''s reporting period. As you expand the date range, additional full historical reporting periods and all ratings estimateDates per broker will be returned.</p>

        '
      operationId: getDetailRatingsForList
      requestBody:
        required: true
        description: Request object for Detail Reatings Data Items.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/detailRatingsRequest'
      responses:
        '200':
          description: Estimate Detail Ratings data items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/detailRatingsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /instrument/rating/grade/list:
    post:
      tags:
      - Ratings
      operationId: post/instrument/rating/grade/list
      x-supportsOffsetBasedPaging: false
      x-supportsOffsetBasedPagingWithoutTotal: false
      x-supportsCursorBasedPaging: false
      x-supportsCursorBasedPagingWithoutTotal: false
      x-supportsPush: false
      x-requiresUser: false
      x-requiresInternalClient: false
      x-disallowUser: false
      x-no-merge: false
      x-maxSortParameterCount: 10
      x-supportsPermissionDeniedResponse: false
      description: List of rating grades for a list of instruments. The list can be restricted to rating grades belonging to particular rating systems.
      summary: Factset List of Rating Grades for a List of Instruments.
      requestBody:
        description: Request Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostInstrumentRatingGradeListRequest'
        required: false
      responses:
        '200':
          $ref: '#/components/responses/PostInstrumentRatingGradeList200Response'
      parameters: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  examples:
    badRequestInvalidParameters:
      summary: Bad Request - Invalid Parameters
      description: This error message occurs when a request parameter is used in which is not recognized by the service. Please revise your request to include only the parameters listed in the specification. Typical causes are spelling mistakes and use of improper casing.
      value:
        status: Bad Request
        timestamp: '2020-06-12 15:58:54.068'
        path: /factset-estimates/v2/{endpoint}
        message: 'Invalid Parameter (s): fakeParameterName1 fakeParameterName2. Please modify your request to use parameters outlined in the specification for this endpoint.'
        subErrors: null
    badRequestDateFormat:
      summary: Bad Request - Date Format
      description: This bad request occurs when a request doesn't use the YYYY-MM-DD in the date parameters. To resolve, convert your date to YYYY-MM-DD.
      value:
        status: Bad Request
        timestamp: '2019-10-31 16:08:07.945'
        path: /factset-estimates/v2/{endpoint}
        message: 'The date parameter ''startDate'' must be in the following date format: YYYY-MM-DD'
        subErrors: null
    notWritable:
      summary: Internal Server Error - Not Writable
      description: This error may be returned when the server encounters an error writing the JSON response.
      value:
        status: Internal Server Error
        timestamp: '2019-11-05 09:48:29.18'
        path: /factset-estimates/v2/{endpoint}
        message: Error writing JSON output
        subErrors: null
    unsupportedMediaType:
      summary: Unsupported Media Type
      description: This bad request occurs when the media type passed in the request is not supported. Currently the APIs only support 'application/json'.
      value:
        status: Unsupported Media Type
        timestamp: '2019-11-05 09:42:27.237'
        path: /factset-estimates/v2/{endpoint}
        message: text/html media type is not supported. Supported media types are application/json
        subErrors: null
    generalException:
      summary: Internal Server Error - General Exception
      description: This is the most general error that can be returned to by the service. Please `Report Issue` to FactSet.
      value:
        status: Internal Server Error
        timestamp: '2019-11-01 10:36:01.944'
        path: /factset-estimates/v2/{endpoint}
        message: Unexpected error
        subErrors: null
    badRequestReadTimeout:
      summary: Bad Request - Read Timeout
      description: This error may be returned if it takes more than 29 seconds to hear back from the data fetch service.
      value:
        status: Bad Request
        timestamp: '2019-11-04 16:18:38.949'
        path: /factset-estimates/v2/{endpoint}
        message: The request took too long. Try again with a smaller request.
        subErrors: null
    badRequestFutureDate:
      summary: Bad Request - Future Date
      description: This error message occurs when a future date is requested in the startDate and endDate parameters. Please revise your request to include dates as of today's current date or any prior historical date.
      value:
        status: Bad Request
        timestamp: '2020-06-12 15:52:48.091'
        path: /factset-estimates/v2/{endpoint}
        message: The use of future dates is not applicable in this endpoint. Please revise your request to include dates up to today's current date.
        subErrors: null
    forbidden:
      summary: Forbidden
      description: The USERNAME-SERIAL attempted to request the endpoint is not authorized to access. The request was a legal request, but the server is refusing to respond. Please reach out to FactSet Account Team for assistance with authorization.
      value:
        status: Forbidden
        timestamp: '2020-06-12 16:08:51.731'
        path: /factset-estimates/v2/{endpoint}
        message: USERNAME-SERIAL does not have permission to use /factset-estimates/v2/{endpoint}
        subErrors: null
    unauthenticated:
      summary: User Authentication Failed
      description: This occurs when a user is not properly authenticated or recognized by the service. Please double check the USERNAME-SERIAL and API-Key used to request and ensure you are within the IP range specified for the Key. Report Issue under 401 error for help with troubleshooting.
      value:
        status: User Authentication Failed
        timestamp: '2019-10-31 16:08:07.945'
        path: /factset-estimates/v2/{endpoint}
        message: User Authentication Failed.
        subErrors: null
    badRequestMalformedJSON:
      summary: Bad Request - Malformed JSON Request
      description: This error may be returned when the request body is specified as JSON, but is not in proper JSON format.
      value:
        status: Bad Request
        timestamp: '2019-11-05 09:48:29.18'
        path: /factset-estimates/v2/{endpoint}
        message: Malformed JSON Request
        subErrors: null
    badRequestRequiredParameter:
      summary: Bad Request - Required Parameter Missing
      description: This error message occurs when the request does not include the required parameters. Required parameters are indicated with a red asterisks symbol in the specification file.
      value:
        status: Bad Request
        timestamp: '2020-06-12 15:48:42.016'
        path: /factset-estimates/v2/{endpoint}
        message: The parameter 'ids' is required and may not be empty.
        subErrors: null
  parameters:
    ids:
      name: ids
      in: query
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 3000
      required: true
      explode: false
      description: 'Security or Entity identifiers. FactSet Identifiers, tickers, CUSIP and SEDOL are accepted input. <p>***ids limit** =  3000 per request*</p> * Make Note - id limit of 3000 for defaults, otherwise the service is limited to a 30 second duration. This can be reached when increasing total number of metrics requested and depth of history. *

        '
      examples:
        oneId:
          summary: One Market Identifier
          value:
          - AAPL-USA
        multipleIds:
          summary: Multiple Market Identifiers
          value:
          - FDS-US
          - AAPL-US
          - MSFT-US
    frequency:
      name: frequency
      in: query
      schema:
        type: string
        enum:
        - D
        - W
        - AM
        - AQ
        - AY
        default: D
      description: "Controls the frequency of the data returned.\n  * **D** = Daily\n  * **W** = Weekly, based on the last day of the week of the start date.\n  * **AM** = Monthly, based on the start date (e.g., if the start date is June 16, data is displayed for June 16, May 16, April 16 etc.).      \n  * **AQ** = Quarterly, based on the start date.\n  * **AY** = Actual Annual, based on the start date. \n"
      examples:
        Daily:
          summary: D - Daily frequency display based on trading calendar
          value: D
        Weekly:
          summary: W - Weekly - based on the last day of the week of the start date
          value: W
        Actual Month:
          summary: AM - Actual Month - based on the startDate (e.g., if the start date is June 16, data is displayed for June 16, May 16, April 16 etc.).
          value: AM
        Actual Annual:
          summary: AY - Actual Annual - based on the startDate
          value: AY
    startDate:
      name: startDate
      in: query
      required: false
      schema:
        type: string
      description: Start date for point in time of estimates expressed in YYYY-MM-DD format.
      example: '2019-07-30'
    endDate:
      name: endDate
      in: query
      required: false
      schema:
        type: string
      description: End date for point in time of estimates expressed in YYYY-MM-DD format.
      example: '2020-07-30'
    includeAll:
      name: includeAll
      in: query
      schema:
        type: boolean
        default: false
      required: false
      description: "Include All filter is used to identify included and excluded broker details from the consensus\n  By default the service would return only the brokers included in the consensus-\n  * **TRUE** = Returns all the brokers included and excluded in the consensus\n  * **FALSE** = Returns only the broker details included in the consensus\n  \n"
  responses:
    '401':
      description: Unauthenticated USERNAME-SERIAL. Ensure you are logged in and have successfully generated an API KEY for the IP range you are connecting from. For more help, select the **Report Issue** in the top right corner of this Developer Portal specification card and choose Connectivity 401 or 403 Responses.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/unauthenticated'
    '415':
      description: Unsupported Media Type. This error may be returned when the caller sends a resource in a format that is not accepted by the server. This can be fixed by ensuring that Content-Type header is set to the correct value. In this instance, "application/json" would be the appropriate value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/unsupportedMediaType'
    '403':
      description: The USERNAME-SERIAL attempted to request the endpoint is not authorized to access. The request was a legal request, but the server is refusing to respond. Please reach out to FactSet Account Team for assistance with authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/forbidden'
    PostInstrumentRatingGradeList200Response:
      description: Successful Response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                nullable: false
                items:
                  type: object
                  nullable: false
                  x-property-sort:
                  - idInstrument
                  - sourceIdentifier
                  - status
                  - ratings
                  properties:
                    idInstrument:
                      nullable: true
                      type: string
                      format: id64
                      x-positive: true
                      description: MDG identifier of the instrument.
                    sourceIdentifier:
                      nullable: true
                      type: string
                      description: Identifier used in the request.
                    status:
                      nullable: false
                      type: object
                      x-property-sort:
                      - code
                      - identifier
                      - details
                      - encryptedDetails
                      description: Error status for the requested identifier.
                      properties:
                        code:
                          nullable: true
                          type: string
                          description: Code of the error condition.
                          x-enum-description:
                          - No error.
                          - The provided identifier does not refer to a valid instrument level identifier.
                          - Not entitled to see data for the identifier.
                          - Unable to resolve the provided identifier.
                          enum:
                          - none
                          - parameter
                          - entitlement
                          - identifierMapping
                        identifier:
                          nullable: true
                          type: string
                          description: Provided identifier.
                        details:
                          nullable: true
                          type: string
                          description: A human-readable, unstructured explanation specific to this occurrence of the problem.
                        encryptedDetails:
                          nullable: true
                          type: string
                          description: Base64-encoded internal details about the error.
                    ratings:
                      nullable: false
                      type: array
                      items:
                        type: object
                        nullable: false
                        x-property-sort:
                        - system
                        - current
                        - previous
                        - change
                        properties:
                          system:
                            nullable: false
                            type: object
                            x-property-sort:
                            - id
                            - name
                            description: Rating system.
                            properties:
                              id:
                                nullable: true
                                type: number
                                format: id32
                                x-positive: true
                                description: Identifier of the rating system.
                              name:
                                nullable: true
                                type: string
                                description: 'Official name of the rating system in the original language, as

                                  supplied by the rating agency.'
                          current:
                            nullable: false
                            type: object
                            x-property-sort:
                            - id
                            - grade
                            - rank
                            - date
                            description: Current rating.
                            properties:
                              id:
                                nullable: true
                                type: number
                                format: id32
                                x-positive: true
                                description: Identifier of the rating grade.
                              grade:
                                nullable: true
                                type: string
                                description: Rating grade.
                              rank:
                                nullable: true
                                type: number
                                format: int32
                                description: 'Rank of the rating grade according to the sort order of the

                                  rating system.'
                              date:
                                nullable: true
                                type: string
                                format: date
                                description: Date on which the instrument was rated.
                          previous:
                            nullable: false
                            type: object
                            x-property-sort:
                            - id
                            - grade
                            - rank
                            - date
                            description: Previous rating.
                            properties:
                              id:
                                nullable: true
                                type: number
                                format: id32
                                x-positive: true
                                description: Identifier of the rating grade.
                              grade:
                                nullable: true
                                type: string
                                description: Rating grade.
                              rank:
                                nullable: true
                                type: number
                                format: int32
                                description: 'Rank of the rating grade according to the sort order of the

                                  rating system.'
                              date:
                                nullable: true
                                type: string
                                format: date
                                description: Date on which the instrument was rated.
                          change:
                            nullable: true
                            type: number
                            format: int32
                            description: 'Rating grade change which is the difference between the rank of the current rating and the rank of the previous rating.

                              Example: If a rating system has AAA, AA, A, B, C, D as possible

                              ratings (from best to worst), then a change from AA to B is

                              represented as -2 and a change from C to AAA is represented

                              as +4.'
                      description: Rating details. See endpoint `/rating/system/get` for details regarding a rating system, endpoint `/rating/grade/listBySystem` for all rating grades of a rating system, and endpoint `/rating/grade/get` for details regarding a rating grade.
                description: 'Unsorted list of instruments with their respective rating grade per rating

                  system.'
              meta:
                type: object
                description: The meta member contains the meta information of the response.
                properties:
                  status:
                    $ref: '#/components/schemas/StatusObject'
                x-property-sort:
                - status
            x-property-sort:
            - data
            - meta
    '500':
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Internal Server Error - Not Writable:
              $ref: '#/components/examples/notWritable'
            Internal Server Error - General Exception:
              $ref: '#/components/examples/generalException'
    '400':
      description: Bad Request. This can occur for several reasons. Please review the "message" for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/badRequestDateFormat'
            Bad Request - Missing Required Parameter:
              $ref: '#/components/examples/badRequestRequiredParameter'
            Bad Request - Future Date:
              $ref: '#/components/examples/badRequestFutureDate'
            Bad Request - Invalid Parameter:
              $ref: '#/components/examples/badRequestInvalidParameters'
            Bad Request - Malformed JSON:
              $ref: '#/components/examples/badRequestMalformedJSON'
            Bad Request - Read Timeout:
              $ref: '#/components/examples/badRequestReadTimeout'
  schemas:
    ids:
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 3000
      description: 'The requested list of security identifiers. Accepted ID types include Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids. * Make Note - id limit of 3000 for defaults, otherwise the service is limited to a 30 second duration. This can be reached when increasing total number of metrics requested and depth of history. *

        '
      example:
      - FDS-US
    endDate:
      type: string
      description: 'The end date requested for a given date range in **YYYY-MM-DD** format. If left blank, the API will default to previous close. Future dates (T+1) are not accepted in this endpoint.

        '
      example: '2019-12-31'
    AttributesMember:
      type: array
      description: Limit the attributes returned in the response to the specified set.
      items:
        type: string
        maxLength: 100
        exclusiveMaximum: false
      maxItems: 50
      uniqueItems: true
    detailRatingsRequest:
      title: Detail Ratings Request Body
      description: Request object for requesting detail ratings estimates.
      type: object
      properties:
        ids:
          $ref: '#/components/schemas/ids'
        startDate:
          $ref: '#/components/schemas/startDate'
        endDate:
          $ref: '#/components/schemas/endDate'
        includeAll:
          $ref: '#/components/schemas/includeAll'
      required:
      - ids
    detailRatingsResponse:
      type: object
      title: Detail Ratings Response
      properties:
        data:
          description: Array of detail ratings estimate objects
          type: array
          items:
            $ref: '#/components/schemas/detailRatings'
          example: []
    consensusRatingsRequest:
      title: Consensus Ratings Request Body
      description: Request object for requesting consensus ratings estimates.
      type: object
      properties:
        ids:
          $ref: '#/components/schemas/ids'
        startDate:
          $ref: '#/components/schemas/startDate'
        endDate:
          $ref: '#/components/schemas/endDate'
        frequency:
          $ref: '#/components/schemas/frequency'
      required:
      - ids
    consensusRatingsResponse:
      type: object
      title: Consensus Ratings Response
      properties:
        data:
          description: Array of consensus ratings estimate objects
          type: array
          items:
            $ref: '#/components/schemas/consensusRatings'
          example: []
    StatusObject:
      type: object
      properties:
        code:
          type: number
          format: int32
          description: The HTTP status code of the response, mirroring the code from the Status-Line of the HTTP response message (see [RFC2616] section 6.1).
          example: 42.5
      description: The status member contains the status code of the response.
      required:
      - code
    errorResponse:
      type: object
      title: Error Response
      properties:
        status:
          description: status
          type: string
          example: Bad Request
        timestamp:
          description: timestamp in YYYY-MM-DD HH:MM:SS.SSS
          type: string
          example: '2019-11-01 11:09:41.918'
          format: date-time
        path:
          description: The Endpoint path {package}/version/{endpoint}
          type: string
          example: /factset-estimates/v2/prices
        message:
          description: The plain text error message
          type: string
          example: Validation Error
        subErrors:
          description: subErrors related to the error message. Null if not applicable.
          type: object
          properties:
            object:
              description: the operation ID
              type: string
            field:
              description: Parameter Field Name
              type: string
            message:
              description: Error message
              type: string
            rejectedValue:
              description: Rejected Values in an Array
              type: array
              items:
                type: string
          example: example_value
    startDate:
      type: string
      description: 'The start date requested for a given date range in **YYYY-MM-DD** format. If left blank, the API will default to previous close. Future dates (T+1) are not accepted in this #endpoint.

        '
      example: '2019-01-01'
    consensusRatings:
      title: Consensus Ratings
      type: object
      properties:
        fsymId:
          type: string
          example: SJY281-R
          nullable: true
        estimateDate:
          description: 'Date of estimate expressed in YYYY-MM-DD format. For more details, visit [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16598)'
          type: string
          format: date
          example: '2017-07-24'
          nullable: true
        buyCount:
          description: The number of Buy ratings taken into account in the calculation of a consensus. This information is shown only for a 100-day consensus.
          type: integer
          example: 5
          nullable: true
        overweightCount:
          description: The number of Overweight ratings taken into account in the calculation of a consensus. This information is shown only for a 100-day consensus.
          type: integer
          example: 1
          nullable: true
        holdCount:
          description: The number of Hold ratings taken into account in t

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/factset/refs/heads/main/openapi/factset-ratings-api-openapi.yml