Factset Index API

openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Index 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: Index
paths:
  /factset-benchmarks/v1/index-snapshot:
    get:
      summary: Factset Index Level Prices, Returns, and Related Information as of a Single Date.
      operationId: getIndexSnapshot
      tags:
      - Index
      description: 'Retrieves Index Level Prices and Returns information as of a specific date. Simply submit a valid Benchmark ID (you can use the /id-list endpoint for a sample list of ids), and date and retrieve Index Level Prices, Returns, and related information.

        '
      parameters:
      - $ref: '#/components/parameters/indexIds'
      - $ref: '#/components/parameters/requestedDate'
      - $ref: '#/components/parameters/returnType'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/calendar'
      responses:
        '200':
          description: An array of Index Level Prices and Returns information as of a single date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/indexSnapshotResponse'
              examples:
                Index Level Prices and Returns snapshot for S&P 500 and Russell 3000 as of 2020-08-06:
                  $ref: '#/components/examples/resultofIndexSnapshotMultiple'
        '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 Retrieves the Index Level Snapshot of Prices and Returns Information for a Given Identifier and Single Date.
      operationId: getIndexSnapshotForList
      tags:
      - Index
      description: 'Retrieves Index Level Prices and Returns information as aligned with FactSet''s Benchmark Data Feed solution. Simply submit a valid Benchmark ID (you can use the /id-list endpoint for a sample list of ids), and date and retrieve Index Level Prices, Returns, and related information.

        '
      requestBody:
        required: true
        description: Requests the Index Level Snapshot for a requested list of identifiers and specified date.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/indexSnapshotRequest'
      responses:
        '200':
          description: An array of Index Level Prices and Returns information as of a single date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/indexSnapshotResponse'
              examples:
                Index Level Prices and Returns snapshot for S&P 500 and Russell 3000 as of 2020-08-06:
                  $ref: '#/components/examples/resultofIndexSnapshotMultiple'
        '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-benchmarks/v1/index-history:
    get:
      summary: Factset Retrieves Index Level Prices and Returns Information for a List of Identifiers and Historical Date Range.
      operationId: getIndexHistory
      tags:
      - Index
      description: 'Retrieves Index Level Prices and Returns information as of a date range requested. Simply submit a valid Benchmark ID (you can use the /id-list endpoint for a sample list of ids), and date range to retrieve Index Level Prices, Returns, and related information.

        '
      parameters:
      - $ref: '#/components/parameters/indexIds'
      - $ref: '#/components/parameters/startDate'
      - $ref: '#/components/parameters/endDate'
      - $ref: '#/components/parameters/frequency'
      - $ref: '#/components/parameters/returnType'
      - $ref: '#/components/parameters/hedgeType'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/calendar'
      - $ref: '#/components/parameters/impliedDate'
      responses:
        '200':
          description: An array of Index Level Prices and Returns information for a requested date range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/indexHistoryResponse'
              examples:
                Index Level Prices and Returns snapshot for S&P 500 and Russell 3000 from 2020-08-05 to 2020-08-06:
                  $ref: '#/components/examples/resultofIndexHistoryMultiple'
        '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 Retrieves Index Level Prices and Returns Information for a List of Identifiers and Historical Date Range.
      operationId: getIndexHistoryForList
      tags:
      - Index
      description: 'Retrieves Index Level Prices and Returns information as aligned with FactSet''s Benchmark Data Feed solution. Simply submit a valid Benchmark ID (you can use the /id-list endpoint for a sample list of ids), and date and retrieve Index Level Prices, Returns, and related information.

        '
      requestBody:
        required: true
        description: Requests Index Level History Prices and Returns for a list of identifiers and specified date range.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/indexHistoryRequest'
      responses:
        '200':
          description: An array of Index Level Prices and Returns information for a requested date range.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/indexHistoryResponse'
              examples:
                Index Level Prices and Returns snapshot for S&P 500 and Russell 3000 from 2020-08-05 to 2020-08-06:
                  $ref: '#/components/examples/resultofIndexHistoryMultiple'
        '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
  /news/article/listByIndex:
    post:
      tags:
      - Index
      operationId: post/news/article/listByIndex
      x-supportsOffsetBasedPaging: false
      x-supportsOffsetBasedPagingWithoutTotal: false
      x-supportsCursorBasedPaging: false
      x-supportsCursorBasedPagingWithoutTotal: true
      x-supportsPush: true
      x-requiresUser: false
      x-requiresInternalClient: false
      x-disallowUser: false
      x-no-merge: false
      x-maxSortParameterCount: 10
      x-supportsPermissionDeniedResponse: false
      summary: Factset News Articles for Instruments That Are Constituents of the Given Indices.
      description: News articles for instruments that are constituents of the given indices.
      requestBody:
        description: Request Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostNewsArticleListByIndexRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/PostNewsArticleListByIndex200Response'
      parameters: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    indexIds:
      title: Index Ids
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 500
      description: Benchmark Identifiers. Reference the helper endpoint **/id-list** to get a sample list of  valid identifiers.
      example:
      - SP50
    calendar:
      title: Calendar
      type: string
      enum:
      - FIVEDAY
      - SEVENDAY
      default: FIVEDAY
      description: Calendar of data returned. SEVENDAY includes weekends.
      example: FIVEDAY
    indexSnapshotRequest:
      type: object
      title: Index Snapshot Request
      properties:
        ids:
          $ref: '#/components/schemas/indexIds'
        date:
          $ref: '#/components/schemas/requestedDate'
        returnType:
          $ref: '#/components/schemas/returnType'
        currency:
          $ref: '#/components/schemas/currency'
        calendar:
          $ref: '#/components/schemas/calendar'
      required:
      - ids
    requestedDate:
      title: Date
      type: string
      description: Date of holding expressed in YYYY-MM-DD format.
      example: '2020-08-06'
    endDate:
      title: End Date
      type: string
      description: Requested end date for Range expressed in YYYY-MM-DD format.
      example: '2019-12-31'
    impliedDate:
      title: Implied Date
      type: string
      enum:
      - Y
      - N
      default: N
      description: This parameter controls the **date** returned in the date field. The default value is **N**. By default, the date field returns the actual date of the observation. This means it will repeat values for weekends and holidays. If  set to **Y**, the date field will return the implied date of the observation, making all the dates unique.
    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
    PostNewsArticleListByIndexRequest:
      x-property-sort:
      - data
      - meta
      description: Request Body
      required:
      - data
      type: object
      properties:
        data:
          type: object
          x-property-sort:
          - identifier
          - filter
          description: The data member contains the request's primary data.
          properties:
            identifier:
              type: object
              x-property-sort:
              - values
              - type
              description: Set of identifiers and their type.
              properties:
                values:
                  description: Set of identifiers to resolve.
                  type: array
                  nullable: false
                  items:
                    type: string
                    minLength: 3
                    exclusiveMinimum: false
                    maxLength: 50
                    exclusiveMaximum: false
                    pattern: ^[B-DF-HJ-NP-TV-Z0-9]{6}-[LR]$|^[A-Z0-9.#&*+]{1,47}-[A-Z0-9]{2,4}$|^[0-9]{3,20}$
                  uniqueItems: true
                  minItems: 1
                  maxItems: 100
                type:
                  type: string
                  description: Type of the identifier.
                  x-enum-description:
                  - MDG identifier of a listing.
                  - FactSet market symbol of a listing.
                  - Regional FactSet ticker symbol, identifying the primary listing in the region.
                  - FactSet Permanent Identifier on listing level.
                  - Regional FactSet Permanent Identifier, identifying the primary listing in the region.
                  enum:
                  - idNotation
                  - tickerExchange
                  - tickerRegion
                  - fdsPermanentIdentifierListing
                  - fdsPermanentIdentifierRegional
              required:
              - values
              - type
            filter:
              description: Criteria that filter the items in the response list; only items that match all of the criteria are returned.
              type: object
              x-property-sort:
              - range
              - categories
              - regions
              - distributor
              - publisher
              - language
              - types
              properties:
                range:
                  type: object
                  format: timeRange
                  properties:
                    start:
                      type: string
                      format: datetime
                      description: The starting point of the time range (inclusive), or `null` to indicate that the time range extends indefinitely into the past.
                      x-allowNullValue: true
                    end:
                      type: string
                      format: datetime
                      description: The ending point of the time range (exclusive), or `null` to indicate that the time range extends indefinitely into the future.
                      x-allowNullValue: true
                  x-property-sort:
                  - start
                  - end
                  required:
                  - start
                  - end
                  description: Time range for matching the news article's date. At most one of the attributes `start` or `end` may be `null`.
                categories:
                  type: object
                  x-property-sort:
                  - ids
                  description: Filter for specific categories of the news article. Use a category system of type news with endpoint `/category/listBySystem` for valid values.
                  properties:
                    ids:
                      type: array
                      nullable: false
                      items:
                        type: number
                        format: id32
                        x-positive: true
                      minItems: 1
                      maxItems: 100
                      uniqueItems: true
                      description: Identifiers of the categories.
                regions:
                  type: object
                  x-property-sort:
                  - ids
                  description: Filter for specific regions of the content of the news article. See endpoint `/basic/region/list` for valid values.
                  properties:
                    ids:
                      type: array
                      nullable: false
                      items:
                        type: number
                        format: id32
                        x-positive: true
                      minItems: 1
                      maxItems: 100
                      uniqueItems: true
                      description: Identifiers of the regions.
                distributor:
                  type: object
                  x-property-sort:
                  - ids
                  description: Filter for specific distributors of the news article. See endpoint `/news/distributor/list` for valid values.
                  properties:
                    ids:
                      type: array
                      nullable: false
                      items:
                        type: number
                        format: id32
                        x-positive: true
                      minItems: 1
                      maxItems: 100
                      uniqueItems: true
                      description: Identifiers of the distributors.
                publisher:
                  type: object
                  x-property-sort:
                  - ids
                  description: Filter for specific publishers of the news article. See endpoint `/news/publisher/list` for valid values.
                  properties:
                    ids:
                      type: array
                      nullable: false
                      items:
                        type: number
                        format: id32
                        x-positive: true
                      minItems: 1
                      maxItems: 100
                      uniqueItems: true
                      description: Identifiers of the publishers.
                language:
                  type: object
                  x-property-sort:
                  - ids
                  description: Filter for specific languages of the news article. See endpoint `/basic/language/list` for valid values.
                  properties:
                    ids:
                      type: array
                      nullable: false
                      items:
                        type: number
                        format: id32
                        x-positive: true
                      minItems: 1
                      maxItems: 100
                      uniqueItems: true
                      description: Identifiers of the languages.
                types:
                  type: object
                  x-property-sort:
                  - ids
                  description: Filter for specific types of the news article. See endpoint `/news/article/type/list` for valid values.
                  properties:
                    ids:
                      type: array
                      nullable: false
                      items:
                        type: number
                        format: id32
                        x-positive: true
                      minItems: 1
                      maxItems: 100
                      uniqueItems: true
                      description: Identifiers of the article types.
          required:
          - identifier
          example: example_value
        meta:
          type: object
          description: The meta member contains the meta information of the request.
          properties:
            attributes:
              $ref: '#/components/schemas/AttributesMember'
            subscription:
              type: object
              description: Object defining the subscription attributes.
              properties:
                minimumInterval:
                  type: number
                  format: int32
                  minimum: 0
                  exclusiveMinimum: false
                  maximum: 5000
                  exclusiveMaximum: false
                  default: 0
                  description: Non-negative number of milliseconds to throttle the update rate from 0ms to 5000ms. Set to 0 for sending updates immediately.
              x-property-sort:
              - minimumInterval
            pagination:
              type: object
              description: Pagination attributes for the cursor-based pagination strategy.
              properties:
                cursor:
                  type: string
                  maxLength: 50
                  exclusiveMaximum: false
                  description: Starting point as returned in the attributes `pagination.next` or `pagination.previous` by a prior invocation of this endpoint, or undefined (default).
                limit:
                  type: number
                  format: int32
                  minimum: 1
                  exclusiveMinimum: false
                  maximum: 500
                  exclusiveMaximum: false
                  default: 20
                  description: Non-negative maximum number of entries to return.
              x-property-sort:
              - cursor
              - limit
          x-property-sort:
          - attributes
          - subscription
          - pagination
          example: example_value
    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-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
    indexSnapshot:
      title: Index Snapshot Object
      type: object
      properties:
        fsymId:
          type: string
          description: Requested Identifier. Must be a valid Benchmark Identifier recognized by FactSet.
          example: SP50
          nullable: true
        date:
          description: The respective date for values as of the date requested in YYYY-MM-DD format.
          type: string
          format: date
          example: '2020-07-01'
          nullable: true
        name:
          description: Proper Name of Index.
          type: string
          example: S&P 500
          nullable: true
        constituentNumber:
          description: The total number of constituents as of the date requested.
          type: integer
          example: 502
          nullable: true
        currency:
          description: Currency Code used in adjustments. If no Currency was requested, the service will default to the local Calendar.
          type: string
          example: USD
          nullable: true
        marketValue:
          description: Index Level Market Capitalization as of the date requested expressed in millions.
          type: number
          format: double
          example: 27696158.012077
          nullable: true
        price:
          description: Index Level Price
          type: number
          format: double
          example: 3349.15600690205
          nullable: true
        priceReturnPercent1D:
          description: Index Level Price - 1 Day percent change
          type: number
          format: double
          example: 0.642620385795123
          nullable: true
        priceReturnPercentQTD:
          description: Index Level Price - Quarter-to-Date percent change
          type: number
          format: double
          example: 8.02735451465131
          nullable: true
        priceReturnPercentYTD:
          description: Index Level Price - Year-to-Date percent change
          type: number
          format: double
          example: 3.66394447660916
          nullable: true
        totalReturnLevel:
          description: Index Level Total Return Amount. (Gross or Net depends on requested returnType)
          type: number
          format: double
          example: 6870.86168040129
          nullable: true
        totalReturnPercent1D:
          description: Index Level Total Return - 1 Day percent change. (Gross or Net depends on requested returnType)
          type: number
          format: double
          example: 0.653957589855003
          nullable: true
        totalReturnPercentQTD:
          description: Index Level Total Return - Quarter-to-Date percent change. (Gross or Net depends on requested returnType)
          type: number
          format: double
          example: 8.17415047623613
          nullable: true
        totalReturnPercentYTD:
          description: Index Level Total Return - Year-to-Date percent change. (Gross or Net depends on requested returnType)
          type: number
          format: double
          example: 4.84152796547426
          nullable: true
        returnType:
          description: The requested Return Type - GROSS or NET
          type: string
          example: GROSS
          nullable: true
        requestId:
          type: string
          description: Benchmark Identifier specified in the request
          example: SP50
    hedgeType:
      title: Hedge Type
      type: string
      enum:
      - UNHEDGED
      - HEDGED
      default: UNHEDGED
      description: The hedge type adjustment used in returns response items. Adjustment can be made for HEDGED and UNHEDGED values that will be included in the return calculation. The service weill default to UNHEDGED.
      example: UNHEDGED
    indexHistoryRequest:
      type: object
      title: Index History Request
      properties:
        ids:
          $ref: '#/components/schemas/indexIds'
        startDate:
          $ref: '#/components/schemas/startDate'
        endDate:
          $ref: '#/components/schemas/endDate'
        frequency:
          $ref: '#/components/schemas/frequency'
        returnType:
          $ref: '#/components/schemas/returnType'
        hedgeType:
          $ref: '#/components/schemas/hedgeType'
        currency:
          $ref: '#/components/schemas/currency'
        calendar:
          $ref: '#/components/schemas/calendar'
        impliedDate:
          $ref: '#/components/schemas/impliedDate'
      required:
      - ids
    indexHistoryResponse:
      title: Index History Response
      type: object
      properties:
        data:
          description: 'Array of Index History response objects.

            '
          type: array
          items:
            $ref: '#/components/schemas/indexHistory'
          example: []
    startDate:
      title: Start Date
      type: string
      description: Requested start date expressed in YYYY-MM-DD format.
      example: '2018-12-31'
    currency:
      title: Currency
      type: string
      description: Currency for response.
      example: USD
    indexSnapshotResponse:
      title: Index Snapshot Response
      type: object
      properties:
        data:
          description: 'Array of index snapshot response objects.

            '
          type: array
          items:
            $ref: '#/components/schemas/indexSnapshot'
          example: []
    returnType:
      title: Return Type
      type: string
      enum:
      - GROSS
      - NET
      default: GROSS
      description: The return type adjustment used in returns response items. Adjustment can be made for GROSS and NET dividends that will be included in the return calculation. The service will default to GROSS.
      example: GROSS
    indexHistory:
      title: Index History Object
      type: object
      properties:
        fsymId:
          type: string
          description: Requested Identifier. Must be a valid Benchmark Identifier recognized by FactSet.
          example: SP50
          nullable: true
        date:
          description: The respective date for values as of the date requested in YYYY-MM-DD format.
          type: string
          format: date
          example: '2020-07-01'
          nullable: true
        name:
          description: Proper Name of Index.
          type: string
          example: S&P 500
          nullable: true
        constituentNumber:
          description: The total number of constituents as of the date requested.
          type: integer
          example: 502
          nullable: true
        currency:
          description: Currency Code used in adjustments. If no Currency was requested, the service will default to LOCAL ('LOC').
          type: string
          example: USD
          nullable: true
        marketValue:
          description: Index Level Market Capitalization as of the date requested expressed in millions.
          type: number
          format: double
          example: 27696158.012077
          nullable: true
        price:
          description: Index Level Price
          type: number
          format: double
          example: 3349.15600690205
          nullable: true
        priceReturnPercent:
          description: Index Level Price Percent Change
          type: number
          format: double
          example: 0.642620385795123
          nullable: true
        totalReturnLevel:
          description: Index Level Total Return Amount
          type: number
          format: double
          example: 6870.86168040129
          nullable: true
        totalReturnPercent:
          description: Index Level Total Return Percent Change
          type: number
          format: double
          example: 0.653957589855003
          nullable: true
        returnType:
          description: The requested Return Type - GROSS or NET
          type: string
          example: GROSS
          nullable: true
        hedgeType:
          description: The requested Hedge Type - HEDGED or UNHEDGED
          type: string
          example: UNHEDGED
          nullable: true
        requestId:
          type: string
          description: Benchmark Identifier specified in the request
          example: SP50
        observationDate:
          description: This field will always return the date of the data that was actually returned.
          type: string
          example: '2020-07-21'
          nullable: true
    frequency:
      title: Frequency
      type: string
      enum:
      - D
      - W
      - M
      - AM
      - CQ
      - AY
      - CY
      default: CY
      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  * **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  * **CQ** = Quarterly based on the last trading day of the calendar quarter (March, June, September, or December).\n  * **AY** = Actual Annual, based on the start date.\n  * **CY** = Calendar Annual, based on the last trading day of the calendar year.\n"
      example: CY
    CursorBasedPaginationOutputObjectWithoutTotal:
      type: object
      description: Pagination attributes for the cursor-based pagination strategy; a total element count is not supported.
      properties:
        next:
          type: string
          description: The next cursor position to use in the parameter `pagination.cursor` for an endpoint that supports cursor-based pagination, otherwise `null`.
          example: example_value
        previous:
          type: string
          description: The previous cursor position to use in the parameter `pagination.cursor` for an endpoint that supports cursor-based pagination. If a previous cursor position is not supported or available, `previous` is `null`.
          example: example_value
      required:
      - next
      - previous
      x-property-sort:
      - next
      - previous
  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
    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
       

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