openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Ranks 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: Ranks
paths:
  /factset-esg/v1/sasb-ranks:
    get:
      tags:
      - Ranks
      summary: Factset Gets Esg Rankings for a Requested List of Ids and Dates.
      operationId: getSasbRanks
      description: "Indicates if a company is a Leader, Above Average, Average, Below Average, or a Laggard; directly mapping from Industry Percentiles (*request IND_PCTL in scores endpoints*). Mapping of ESG Ranks to Industry Percentile Ranges is as follows - \n\n|Rank|Industry Percentile Range (%)|\n|||\n|Leader|90 - 100|\n|Above Average|70 - 89.9|\n|Average|30 - 69.9|\n|Below Average|10 - 29.9|\n|Laggard|0 - 9.9|\n\nIndustry classifications follow SICS, SASB's Industry Classification System. Using the Adjusted Insight scores, Industry Percentiles are generated for all companies. Companies with five or more articles in a year get ranked in a first pass, then companies with filled-in values are interpolated without forcing the ranking of higher-volume companies up or down.  In the case where a company falls into an industry with fewer than 7 high or medium volume companies the Sector Percentile is inserted in the place of the Industry Percentile score.\n<p>Only Vaild for ALLCATEGORIES and MATERIALITY categories.</p>\n"
      parameters:
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/rankCategories'
      - $ref: '#/components/parameters/startDate'
      - $ref: '#/components/parameters/endDate'
      - $ref: '#/components/parameters/frequency'
      - $ref: '#/components/parameters/calendar'
      responses:
        '200':
          description: The SASB Ranks response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sasbRanksResponse'
              examples:
                ESG Ranks for multiple entities:
                  $ref: '#/components/examples/multipleSasbRanks'
        '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:
      - Ranks
      summary: Factset Get Esg Ranks for a Large List of Ids and Specified Date Range.
      description: "Indicates if a company is a Leader, Above Average, Average, Below Average, or a Laggard; directly mapping from Industry Percentiles (*request IND_PCTL in scores endpoints*). Mapping of ESG Ranks to Industry Percentile Ranges is as follows - \n\n|Rank|Industry Percentile Range (%)|\n|||\n|Leader|90 - 100|\n|Above Average|70 - 89.9|\n|Average|30 - 69.9|\n|Below Average|10 - 29.9|\n|Laggard|0 - 9.9|\n\nIndustry classifications follow SICS, SASB's Industry Classification System. Using the Adjusted Insight scores, Industry Percentiles are generated for all companies. Companies with five or more articles in a year get ranked in a first pass, then companies with filled-in values are interpolated without forcing the ranking of higher-volume companies up or down.  In the case where a company falls into an industry with fewer than 7 high or medium volume companies the Sector Percentile is inserted in the place of the Industry Percentile score.\n<p>Only Vaild for ALLCATEGORIES and MATERIALITY categories.</p>\n"
      operationId: getSasbRanksPost
      requestBody:
        required: true
        description: The SASB Ranks Request Object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sasbRanksRequest'
      responses:
        '200':
          description: The SASB Ranks response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sasbRanksResponse'
              examples:
                ESG Ranks for multiple entities:
                  $ref: '#/components/examples/multipleSasbRanks'
        '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
components:
  parameters:
    rankCategories:
      name: categories
      in: query
      schema:
        type: array
        default:
        - ALL
        items:
          type: string
        minItems: 1
        maxItems: 28
      required: false
      explode: false
      description: "The Categories representing overall or composite rankings from all underlying 26 SASB Categories.\n\n### SASB Categories\n|**SASB Category Inputs**|**Description**|\n|||\n|**ALLCATEGORIES**|**All Categories** - The company's overall SASB Rank. This value is equal to the cumulative average of all 26 SASB categories.\n|**MATERIALITY**|**Materiality** - The composite rank of all 'material' SASB categories for the given entity. For more information on SASB's Materiality Map, visit [materiality.sasb.org](https://materiality.sasb.org/)|\n\n### Helper Input\n**ALL** = Simply gives the ability to request all categories in a single request without having to explicitly list each available category. \n"
      example:
      - ALLCATEGORIES
      - MATERIALITY
    ids:
      name: ids
      in: query
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 1000
      required: true
      explode: false
      description: 'Security or Entity identifiers. FactSet Identifiers, tickers, CUSIP, SEDOL, and ISIN are accepted inputs. <p>***ids limit** =  1000 per request*</p> *<p>Make note, GET Method URL request lines are also limited to a total length of 8192 bytes (8KB). In cases where the service allows for thousands of ids, which may exceed this request line limit of 8KB, its advised for any requests with large request lines to be requested through the respective "POST" method.</p>*

        '
      examples:
        oneId:
          summary: One Market Identifier
          value:
          - AAPL-USA
        multipleIds:
          summary: Multiple Market Identifiers
          value:
          - GOOGL-US
          - AAPL-US
          - MSFT-US
    frequency:
      name: frequency
      in: query
      schema:
        type: string
        enum:
        - D
        - W
        - M
        - CY
        - ''
        default: D
      description: "Controls the display frequency of the data returned.\n  * **D** = Daily\n  * **W** = Weekly, based on the last day of the week of the start date.\n  * **M** = Monthly, based on the last trading day of the month.\n  * **CY** = Calendar Annual, based on the last trading day of the calendar year.\n  \n"
    startDate:
      name: startDate
      in: query
      required: false
      schema:
        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 latest available completed period.

        '
      example: '2018-12-31'
    endDate:
      name: endDate
      in: query
      required: false
      schema:
        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 latest available completed period.

        '
      example: '2019-12-31'
    calendar:
      name: calendar
      in: query
      schema:
        type: string
        enum:
        - FIVEDAY
        - SEVENDAY
        - LOCAL
        default: SEVENDAY
      description: Calendar of data returned. SEVENDAY includes weekends. LOCAL calendar will default to the securities' trading calendar which excludes date records for respective holiday periods.
      example: FIVEDAY
  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-esg/v1/{endpoint}
        message: 'Invalid Parameter (s): fakeParameterName1 fakeParameterName2. Please modify your request to use parameters outlined in the specification for this endpoint.'
        subErrors: null
    multipleSasbRanks:
      summary: ESG Ranks for a small list of companies
      description: 'The Materiality ESG Rank for a list of companies with different Rank Values.

        '
      value:
      - date: '2021-03-17'
        fsymId: 000Y35-E
        requestId: UDR
        sasbCategory: MATERIALITY
        sasbRank: Leader
      - date: '2021-03-17'
        fsymId: 0DX8BF-E
        requestId: QRVO
        sasbCategory: MATERIALITY
        sasbRank: Above Average
      - date: '2021-03-17'
        fsymId: 0BTZL3-E
        requestId: PLD
        sasbCategory: MATERIALITY
        sasbRank: Average
      - date: '2021-03-17'
        fsymId: 000T4W-E
        requestId: PH
        sasbCategory: MATERIALITY
        sasbRank: Below Average
      - date: '2021-03-17'
        fsymId: 0018R5-E
        requestId: EIX
        sasbCategory: MATERIALITY
        sasbRank: Laggard
    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-esg/v1/{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-esg/v1/{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-esg/v1/{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-esg/v1/{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-esg/v1/{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-esg/v1/{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 used to request the endpoint is not authorized to access it. 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-esg/v1/{endpoint}
        message: USERNAME-SERIAL does not have permission to use /factset-esg/v1/{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-esg/v1/{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-esg/v1/{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-esg/v1/{endpoint}
        message: The parameter 'ids' is required and may not be empty.
        subErrors: null
  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 used to request the endpoint is not authorized to access it. 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'
    '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: 1000
      description: 'Security or Entity identifiers. FactSet Identifiers, tickers, CUSIP and SEDOL are accepted input. <p>***ids limit** =  1000 per request*</p> *<p>Make note, GET Method URL request lines are also limited to a total length of 8192 bytes (8KB). In cases where the service allows for thousands of ids, which may exceed this request line limit of 8KB, its advised for any requests with large request lines to be requested through the respective "POST" method.</p>*

        '
      example:
      - AAPL-USA
    calendar:
      type: string
      enum:
      - FIVEDAY
      - SEVENDAY
      - LOCAL
      default: SEVENDAY
      description: Calendar of data returned. SEVENDAY includes weekends. LOCAL calendar will default to the securities' trading calendar which excludes date records for respective holiday periods.
      example: FIVEDAY
    sasbRanksResponse:
      type: object
      title: SASB Ranks Response
      properties:
        data:
          description: Array of SASB Ranks Objects
          type: array
          items:
            $ref: '#/components/schemas/sasbRanks'
          example: []
    endDate:
      type: string
      description: 'The end date requested for a given date range in **YYYY-MM-DD** format. Data is available on a Fiscal Annual periodicity, but updated Daily. If left blank, the API will default to previous close. Future dates (T+1) are not accepted in this endpoint.

        '
      example: '2019-12-31'
    sasbRanks:
      title: SASB Ranks Object
      type: object
      properties:
        date:
          description: Date for the period requested expressed in YYYY-MM-DD format.
          type: string
          format: date
          example: '2020-09-30'
          nullable: true
        fsymId:
          description: FactSet Entity Identifier. Six alpha-numeric characters, excluding vowels, with a -E suffix (XXXXXX-E).
          type: string
          example: 000BJT-E
          nullable: true
        requestId:
          description: Identifier that was used for the request.
          type: string
          example: ADBE-US
        sasbCategory:
          description: The specific SASB 'category' the Rank is referring to.
          type: string
          example: ALLCATEGORIES
          nullable: true
        sasbRank:
          description: "The SASB Rank for the given category in Proper format.\n  |Rank|Industry Percentile Range (%)|\n  |||\n  |Leader|90 - 100|\n  |Above Average|70 - 89.9|\n  |Average|30 - 69.9|\n  |Below Average|10 - 29.9|\n  |Laggard|0 - 9.9|\n"
          type: string
          example: Average
          nullable: true
    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-esg/v1/sasb-scores
        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
          nullable: true
          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. Data is available on a Fiscal Annual periodicity, but updated Daily. If left blank, the API will default to previous close. Future dates (T+1) are not accepted in this endpoint.

        '
      example: '2019-01-01'
    rankCategories:
      type: array
      default:
      - ALL
      items:
        type: string
      minItems: 1
      maxItems: 2
      description: "The Categories representing overall or composite rankings from all underlying 26 SASB Categories.\n\n### SASB Categories\n|**SASB Category Inputs**|**Description**|\n|||\n|**ALLCATEGORIES**|**All Categories** - The company's overall SASB Rank. This value is equal to the cumulative average of all 26 SASB categories.\n|**MATERIALITY**|**Materiality** - The composite rank of all 'material' SASB categories for the given entity. For more information on SASB's Materiality Map, visit [materiality.sasb.org](https://materiality.sasb.org/)|\n\n### Helper Input\n**ALL** = Simply gives the ability to request all categories in a single request without having to explicitly list each available category. \n"
      example:
      - ALLCATEGORIES
      - MATERIALITY
    sasbRanksRequest:
      title: SASB Scores Request Body
      description: SASB Scores Request Body
      type: object
      properties:
        ids:
          $ref: '#/components/schemas/ids'
        categories:
          $ref: '#/components/schemas/rankCategories'
        startDate:
          $ref: '#/components/schemas/startDate'
        endDate:
          $ref: '#/components/schemas/endDate'
        frequency:
          $ref: '#/components/schemas/frequency'
        calendar:
          $ref: '#/components/schemas/calendar'
      required:
      - ids
    frequency:
      type: string
      enum:
      - D
      - W
      - M
      - CY
      - ''
      default: D
      description: "Controls the display frequency of the data returned.\n  * **D** = Daily\n  * **W** = Weekly, based on the last day of the week of the start date.\n  * **M** = Monthly, based on the last trading day of the month.\n  * **CY** = Calendar Annual, based on the last trading day of the calendar year.\n  \n"
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation