Factset Factset Etf API

openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Factset Etf 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: Factset Etf
paths:
  /factset-etf/v1/reference:
    get:
      summary: Factset Return reference data for an ETF.
      description: 'Returns reference data items for Exchange Traded Funds.

        '
      tags:
      - Factset Etf
      operationId: getEtfReferenceData
      parameters:
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/metrics'
      - $ref: '#/components/parameters/categories'
      responses:
        '200':
          $ref: '#/components/responses/EtfReferenceDataResponse'
        '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'
    post:
      summary: Factset Fetch Reference Data for a large list of ETF securities.
      description: 'Returns reference data items for a list of Exchange Traded Funds.

        '
      tags:
      - Factset Etf
      operationId: getEtfReferenceDataForList
      requestBody:
        description: Request object for Exchange Traded Funds
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EtfReferenceDataRequest'
            examples:
              ETF Reference Data Metrics Request:
                $ref: '#/components/examples/EtfReferenceDataMetricsRequest'
              ETF Reference Data Category Request:
                $ref: '#/components/examples/EtfReferenceDataCategoryRequest'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/EtfReferenceDataResponse'
        '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'
  /factset-etf/v1/metrics:
    get:
      summary: Factset Available ETF metrics
      operationId: getEtfMetrics
      tags:
      - Factset Etf
      description: 'Returns a list of available metrics that can be used in the `metrics` parameter of related endpoints. Leave _category_ blank to request all available items.

        '
      parameters:
      - $ref: '#/components/parameters/category'
      responses:
        '200':
          $ref: '#/components/responses/MetricsResponse'
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-etf/v1/{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-etf/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-etf/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-etf/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-etf/v1/{endpoint}
        message: Unexpected error
        subErrors: null
    EtfReferenceDataMetricsRequest:
      description: ETF Reference Data Metrics Request
      value:
        ids:
        - EQAL-US
        metrics:
        - factsetEntityId
        - name
        - launchDate
        - fundCurrency
    EtfReferenceDataResponse:
      description: ETF Reference Data Response
      value:
        data:
        - requestId: EQAL-US
          fsymId: Q09R75-S
          factsetEntityId: 0F1QFW-E
          name: Invesco Russell 1000 Equal Weight ETF
          launchDate: '2014-12-23'
          eftBrandName: Invesco
          fundCurrency: USD
          issuerFactsetEntityId: 0033W4-E
    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-etf/v1/{endpoint}
        message: The request took too long. Try again with a smaller request.
        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-etf/v1/{endpoint}
        message: USERNAME-SERIAL does not have permission to use /factset-etf /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-etf/v1/{endpoint}
        message: User Authentication Failed.
        subErrors: null
    EtfReferenceDataCategoryRequest:
      description: ETF Refernece Data Category Request
      value:
        ids:
        - EQAL-US
        categories:
        - REFERENCE
    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-etf/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-etf/v1/{endpoint}
        message: The parameter 'ids' is required and may not be empty.
        subErrors: null
  parameters:
    ids:
      name: ids
      in: query
      description: 'The list of ETF identifiers. Accepted identifer types include FactSet Permanent Ids, Tickers, CUSIP, SEDOL, ISIN. <p>***ids limit** =  3000 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 lead to exceeding this request line limit of 8KB, its advised for any requests with large request lines to be requested through the respective "POST" method.</p>*

        '
      schema:
        $ref: '#/components/schemas/ids'
      required: true
      explode: false
    category:
      name: category
      description: 'The available categories that can be used to select collections of metrics for use within the ETF endpoints.

        |category|description|

        |||

        |BENCHMARK_DETAILS|Details surrounding the underlying Benchmark Id and Segment Banchmark|

        |CLASSIFICATION|FactSet Fund Classification Codes and Names, across Asset Class, Broad  Geography, Fund Categories, Focus, Niche, and more.|

        |COSTS_FEES|Expenses and Fees such as capital gains, expense ratio, management fees, and more.|

        |COUNTERPARTY|Credit and Swap Counterparty details|

        |CREATE_REDEEM|Creation and Redemption Sizes|

        |DESCRIPTIVE|General Descriptive information such as name, objectives, issuer details, launch dates, website, and more.|

        |DISTRIBUTIONS|Dividend Dates, Dividend Treatmetns, Min/Max Cap Gains|

        |DOCUMENTATION|Details surrounding reporting information.|

        |GEARING|Leverage factors, inverse flags, and more.|

        |HEDGE|Hedging Information|

        |RISK|CIFSC Risk Ratings|

        |SERVICE_PROVIDERS|Distributors, issuers, and Advisor details|

        |STATUS|Actively Managed Flags|

        |STRATEGY|Segment Codes, selection criteria, strategy codes, weighting schemes, and lending details.|

        |STRUCTURE|ETF Type, backing codes, synthetic types, ucits compliance, legal structures, and more.|

        |TAX|Tax Types, distribution takes, K1 Flags, and more.|

        '
      in: query
      schema:
        $ref: '#/components/schemas/category'
      required: false
      explode: false
    metrics:
      name: metrics
      description: 'List of individdual data items for Exchange Traded Funds. By default only the fsymId and requestId are returned. To fetch a list of all available data items, use the **/metrics** endpoint.

        '
      in: query
      schema:
        $ref: '#/components/schemas/metrics'
      required: false
      explode: false
    categories:
      name: categories
      in: query
      schema:
        $ref: '#/components/schemas/categories'
      required: false
      explode: false
      description: 'Groupings of `metrics` data items. Supply a list of categories below to return collections of data items in response.

        |category|description|

        |||

        |BENCHMARK_DETAILS|Details surrounding the underlying Benchmark Id and Segment Banchmark|

        |CLASSIFICATION|FactSet Fund Classification Codes and Names, across Asset Class, Broad  Geography, Fund Categories, Focus, Niche, and more.|

        |COSTS_FEES|Expenses and Fees such as capital gains, expense ratio, management fees, and more.|

        |COUNTERPARTY|Credit and Swap Counterparty details|

        |CREATE_REDEEM|Creation and Redemption Sizes|

        |DESCRIPTIVE|General Descriptive information such as name, objectives, issuer details, launch dates, website, and more.|

        |DISTRIBUTIONS|Dividend Dates, Dividend Treatmetns, Min/Max Cap Gains|

        |DOCUMENTATION|Details surrounding reporting information.|

        |GEARING|Leverage factors, inverse flags, and more.|

        |HEDGE|Hedging Information|

        |RISK|CIFSC Risk Ratings|

        |SERVICE_PROVIDERS|Distributors, issuers, and Advisor details|

        |STATUS|Actively Managed Flags|

        |STRATEGY|Segment Codes, selection criteria, strategy codes, weighting schemes, and lending details.|

        |STRUCTURE|ETF Type, backing codes, synthetic types, ucits compliance, legal structures, and more.|

        |TAX|Tax Types, distribution takes, K1 Flags, and more.|

        '
  responses:
    MetricsResponse:
      description: Metrics Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MetricsResponse'
    '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'
    EtfReferenceDataResponse:
      description: ETF Reference Data Response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EtfReferenceDataResponse'
          examples:
            ETF Reference Data:
              $ref: '#/components/examples/EtfReferenceDataResponse'
    '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 - Invalid Parameter:
              $ref: '#/components/examples/badRequestInvalidParameters'
            Bad Request - Malformed JSON:
              $ref: '#/components/examples/badRequestMalformedJSON'
            Bad Request - Read Timeout:
              $ref: '#/components/examples/badRequestReadTimeout'
  schemas:
    EtfReferenceData:
      title: ETF Reference Data
      type: object
      description: Reference data items for a ETF security.
      properties:
        requestId:
          description: Security identifier used in the request.
          type: string
        fsymId:
          description: FactSet Permanent Security Identifier.
          type: string
      additionalProperties: true
      required:
      - requestId
      - fsymId
    ids:
      title: ids
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 3000
      description: List of ETF identifiers.
      example:
      - EQAL-US
      - VEUR-GB
    EtfReferenceDataResponse:
      title: ETF Reference Data Response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EtfReferenceData'
    metrics:
      title: metrics
      description: 'List of data items for Exchange Traded Funds. To fetch a list of all available data items, use the **/metrics** endpoint.

        '
      type: array
      items:
        type: string
      example:
      - factsetEntityId
      - name
      - launchDate
    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-etf/v1/references
        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
    Metric:
      title: Metric Object
      type: object
      properties:
        metric:
          description: 'Metric identifier to be used as `metrics` input in _ETF_ endpoints.

            '
          type: string
          example: name
        name:
          description: Plain text name of the metric.
          type: string
          example: Fund name
        category:
          $ref: '#/components/schemas/category'
        dataType:
          description: "The data type for the metric. Each dataType is defined below -\n  * **DATE** - date format expressed in YYYY-MM-DD.\n  * **DOUBLE** - A double is a FactSet data type, similar to a float or an integer. A double represents numeric data but provides for a greater amount of decimal precision than the float data type. Double values have up to 15 digits of precision, while float values have up to 7 digits (integers have up to 10 digits).\n  * **INTEGER** - An integer is a whole number or zero (i.e., integers do not include decimals). Integers can be positive or negative.\n  * **STRING** - A string value is an ASCII character. A string is a sequence of ASCII characters. String value and text value are synonymous. Function will hold data for multiple time-periods, as well as for many companies (i.e., two-dimensional value). The STRING_ARRAY function returns data using a vertical orientation (e.g., down a column)\n"
          type: string
          enum:
          - DATE
          - DOUBLE
          - INTEGER
          - STRING
      required:
      - metric
    MetricsResponse:
      title: Metrics Response
      type: object
      properties:
        data:
          description: 'Array of metric objects representing the metrics that can be requested from the Exchange Traded Funds APIs.

            '
          type: array
          items:
            $ref: '#/components/schemas/Metric'
    categories:
      title: categories
      type: array
      items:
        $ref: '#/components/schemas/category'
      description: "Selects the ETF metrics by category -\n  |category|description|\n  |||\n  |BENCHMARK_DETAILS|Details surrounding the underlying Benchmark Id and Segment Banchmark|\n  |CLASSIFICATION|FactSet Fund Classification Codes and Names, across Asset Class, Broad  Geography, Fund Categories, Focus, Niche, and more.|\n  |COSTS_FEES|Expenses and Fees such as capital gains, expense ratio, management fees, and more.|\n  |COUNTERPARTY|Credit and Swap Counterparty details|\n  |CREATE_REDEEM|Creation and Redemption Sizes|\n  |DESCRIPTIVE|General Descriptive information such as name, objectives, issuer details, launch dates, website, and more.|\n  |DISTRIBUTIONS|Dividend Dates, Dividend Treatmetns, Min/Max Cap Gains|\n  |DOCUMENTATION|Details surrounding reporting information.|\n  |GEARING|Leverage factors, inverse flags, and more.|\n  |HEDGE|Hedging Information|\n  |RISK|CIFSC Risk Ratings|\n  |SERVICE_PROVIDERS|Distributors, issuers, and Advisor details|\n  |STATUS|Actively Managed Flags|\n  |STRATEGY|Segment Codes, selection criteria, strategy codes, weighting schemes, and lending details.|\n  |STRUCTURE|ETF Type, backing codes, synthetic types, ucits compliance, legal structures, and more.|\n  |TAX|Tax Types, distribution takes, K1 Flags, and more.|\n"
    EtfReferenceDataRequest:
      title: ETF Reference Data Request
      type: object
      properties:
        ids:
          $ref: '#/components/schemas/ids'
        metrics:
          $ref: '#/components/schemas/metrics'
        categories:
          $ref: '#/components/schemas/categories'
      required:
      - ids
    category:
      title: category
      type: string
      enum:
      - BENCHMARK_DETAILS
      - CLASSIFICATION
      - COSTS_FEES
      - COUNTERPARTY
      - CREATE_REDEEM
      - DESCRIPTIVE
      - DISTRIBUTIONS
      - DOCUMENTATION
      - GEARING
      - HEDGE
      - RISK
      - SERVICE_PROVIDERS
      - STATUS
      - STRATEGY
      - STRUCTURE
      - TAX
      description: 'Filters the list of ETF metrics by major category - ||| |category|description| |BENCHMARK_DETAILS|description|

        '
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation