openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Id 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: Id
paths:
  /factset-benchmarks/v1/id-list:
    get:
      summary: Factset Returns a Sample List of Benchmark Identifiers and the Benchmark Categorization to Use in Other Benchmark Api Endpoints.
      operationId: getBenchmarkIds
      tags:
      - Id
      description: Returns a **sample** list of Benchmark Identifiers to use in other Benchmark API endpoints. This is a supporting API to be use alongside the other Benchmark API endpoints. For example, use the fsymID value returned in this response as the input to your `ids` parameter in the /constituents endpoint to return constituents for that id.<p> *This is not the full list of benchmark ids allowed in this service, but rather a representation of the most commonly requested. For complete assistance with ID lookup or concordance services, please reach out to FactSet Support. *</p>
      parameters:
      - $ref: '#/components/parameters/familyFilter'
      responses:
        '200':
          description: List of sample Benchmark Ids
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/benchmarkIdListResponse'
              examples:
                Result of Benchmark Constituent SPY-US:
                  $ref: '#/components/examples/resultofBenchmarkID-TOPIX'
        '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:
      summary: Factset Returns a Sample List of Benchmark Identifiers and the Benchmark Categorization to Use in Other Benchmark Api Endpoints.
      operationId: getBenchmarkIdsForList
      tags:
      - Id
      description: Returns a **sample** list of Benchmark Identifiers to use in other Benchmark API endpoints. This is a supporting API to be use alongside the other Benchmark API endpoints. For example, use the fsymID value returned in this response as the input to your `ids` parameter in the /constituents endpoint to return constituents for that id.<p> *This is not the full list of benchmark ids allowed in this service, but rather a representation of the most commonly requested. For complete assistance with ID lookup or concordance services, please reach out to FactSet Support.*</p>
      requestBody:
        required: true
        description: Requests a sample list of identifiers that can be used in other Benchmarks API endpoints.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/benchmarkIdListRequest'
      responses:
        '200':
          description: List of sample Benchmark Ids
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/benchmarkIdListResponse'
              examples:
                Result of Benchmark Constituent SPY-US:
                  $ref: '#/components/examples/resultofBenchmarkID-TOPIX'
        '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:
    familyFilter:
      name: familyFilter
      in: query
      required: false
      description: 'Highest Level Filter to search by common Benchmark Families, such as S&P, MSCI, or Russell. This will retrieve all related benchmark ids. For further filtering, use the response items such as the categoryDescription field. Leave blank if you wish to see a full sample list of ids. requested-

        * **CHINA & HK INDICES** - Major Hong Kong and China Indices, such as Hang Seng Index (HSI-HKX)

        * **DOW JONES** - Dow Jones Global, Regions, Countries, Titans.

        * **FACTSET MARKET INDICES** - Regional and Country Indices defined by FactSet

        * **FTSE** - FTSE Global, UK, Global All Cap, World, Xinhua, European, GWA, JSE, Multinationals, and Style indices

        * **GLOBAL INDICES** - A mix of major indices across the globe.

        * **MSCI** - MSCI All Country, Asia Pacific, Thematic & Strategy, Emerging, Developed, US.

        * **RUSSELL** - US, Global, and Nomura.

        * **S&P** - US, ASX, Select Industry, BMI, Global, Thematic, Emerging, TSX.

        * **STOXX** - Total Market, Europe, and Nordic

        * **TOPIX** - Topix Indices, such as TOPIX 500 (182301)

        '
      schema:
        type: string
        enum:
        - CHINA_HK_INDICES
        - DOW_JONES
        - FACTSET_MARKET_INDICES
        - FTSE
        - GLOBAL_INDICES
        - MSCI
        - RUSSELL
        - SP
        - STOXX
        - TOPIX
  examples:
    badRequestInvalidParameters:
      summary: Bad Request - Passing invalid Benchmark Identifier
      description: This error message occurs when user is passing Invalid Identifier. Please use the helper endpoint */id-list* for sample Benchmark Identifiers.
      value:
        status: Forbidden
        timestamp: '2020-07-10 15:01:43.634'
        path: /factset-benchmarks/v1/constituents
        message: User is not authorized for the id requested, please reach out to FactSet for support
        subErrors: null
    resultofBenchmarkID-TOPIX:
      summary: The list of Benchmark Ids under the family TOPIX
      description: Result of requesting a sample list of using familyFilter set to TOPIX. Each fsymId represents a unique Benchmark Id that can be used in other benchmark endpoints.
      value:
        data:
        - fsymId: '180511'
          name: Tokyo Stock Exchange 2nd Section
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '152470'
          name: Tokyo Stock Exchange Mothers
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '152471'
          name: Tokyo Stock Exchange REIT
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '180460'
          name: TOPIX
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '182297'
          name: TOPIX 100
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '152469'
          name: TOPIX 1000
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '182301'
          name: TOPIX 500
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '182295'
          name: TOPIX Core 30
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '182296'
          name: TOPIX Large 70
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '180710'
          name: TOPIX Large Cap
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '182300'
          name: TOPIX Mid 400
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '180711'
          name: TOPIX Mid Cap
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '182302'
          name: TOPIX Small
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
        - fsymId: '180712'
          name: TOPIX Small Cap
          familyName: TOPIX
          market: TOPIX Indices
          categoryDescription: TOPIX Indices
    badRequestMoreThanOneBenchmarkIdentifier:
      summary: Bad Request - More Than One Benchmark Identifier
      description: This error message occurs when user is passing more than one identifier as an input.
      value:
        status: Bad Request
        timestamp: '2020-07-02 12:37:52.731'
        path: /factset-benchmarks/v1/constituents
        message: You submitted 2 ids. The max number of ids you may submit is 1. Please try again with fewer ids.
        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: '2020-07-02 11:52:36.464'
        path: /factset-benchmarks/v1/{endpoint}
        message: 'The date parameter 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-benchmarks/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: '2020-07-02 09:42:27.237'
        path: /factset-benchmarks/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-benchmarks/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: '2020-07-02 16:18:38.949'
        path: /factset-benchmarks/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 date 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-30 13:38:36.528'
        path: /factset-benchmarks/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 attempted to request the endpoint/ID which 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-07-02 17:21:52.197'
        path: /factset-benchmarks/v1/{endpoint}
        message: User is not authorized for the id requested, please reach out to FactSet for support
        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: '2020-07-02 16:08:07.945'
        path: /factset-benchmarks/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: '2020-07-02 11:59:09.649'
        path: /factset-benchmarks/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-30 13:22:09.053'
        path: /factset-benchmarks/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 - Unsupported Media Type:
              $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 - forbidden:
              $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 - More Than One Benchmark Identifier:
              $ref: '#/components/examples/badRequestMoreThanOneBenchmarkIdentifier'
            Bad Request - Malformed JSON:
              $ref: '#/components/examples/badRequestMalformedJSON'
            Bad Request - Read Timeout:
              $ref: '#/components/examples/badRequestReadTimeout'
  schemas:
    benchmarkIdList:
      title: Benchmark Id List Object
      type: object
      properties:
        fsymId:
          type: string
          description: Benchmark Id
          example: '990100'
          nullable: true
        name:
          type: string
          description: Name of the Benchmark ID
          example: MSCI World Index
          nullable: true
        familyName:
          type: string
          description: Name of the Benchmarks Family
          example: MSCI
          nullable: true
        market:
          type: string
          description: Market grouping related to the Benchmark Family
          example: Developed
          nullable: true
        categoryDescription:
          type: string
          description: Extended name or description of Benchmark Family & Market
          example: International Indices
          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-benchmarks/v1/{endpoint}
        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
    benchmarkIdListRequest:
      type: object
      title: Benchmark Id List Request
      properties:
        familyFilter:
          $ref: '#/components/schemas/familyFilter'
    benchmarkIdListResponse:
      title: Benchmark Id List Response
      type: object
      properties:
        data:
          description: 'Array of Benchmark Ids and their respective categorizations.

            '
          type: array
          items:
            $ref: '#/components/schemas/benchmarkIdList'
          example: []
    familyFilter:
      title: Family Filter
      description: 'Highest Level Filter to search by common Benchmark Families, such as S&P, MSCI, or Russell. This will retrieve all related benchmark ids. For further filtering, use the response items such as the categoryDescription field. Leave blank if you wish to see a full sample list of ids. requested-

        * **CHINA & HK INDICES** - Major Hong Kong and China Indices, such as Hang Seng Index (HSI-HKX)

        * **DOW JONES** - Dow Jones Global, Regions, Countries, Titans.

        * **FACTSET MARKET INDICES** - Regional and Country Indices defined by FactSet

        * **FTSE** - FTSE Global, UK, Global All Cap, World, Xinhua, European, GWA, JSE, Multinationals, and Style indices

        * **GLOBAL INDICES** - A mix of major indices across the globe.

        * **MSCI** - MSCI All Country, Asia Pacific, Thematic & Strategy, Emerging, Developed, US.

        * **RUSSELL** - US, Global, and Nomura.

        * **S&P** - US, ASX, Select Industry, BMI, Global, Thematic, Emerging, TSX.

        * **STOXX** - Total Market, Europe, and Nordic

        * **TOPIX** - Topix Indices, such as TOPIX 500 (182301)

        '
      type: string
      enum:
      - CHINA_HK_INDICES
      - DOW_JONES
      - FACTSET_MARKET_INDICES
      - FTSE
      - GLOBAL_INDICES
      - MSCI
      - RUSSELL
      - SP
      - STOXX
      - TOPIX
      example: MSCI
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation