openapi: 3.0.0
info:
  title: Factset SDF Download API
  version: 1.0.0
  contact:
    name: Team Mustang
    email: teammustang@factset.com
  description: >-
    The Standard DataFeed (SDF) Download API provides an alternative method for
    users to request and retrieve SDF packages (schemas & bundles). This service
    is not a direct replacement and does not have 100% feature parity with the
    Loader Application. This API provides an alternative for users who are
    unable to utilize the Loader application due to following reasons:
      - Inability to install 3rd party executables due to Corporate Security policies  
      - Inability to utilize the Loader application due to limitations or restrictions with the environment used to consume Standard Datafeed
      - Clients who are utilizing existing delivery method like FTP, who may want to use a more secured & modern solution  

     This API allows users to retrieve
     - SDF packages(excluding Quant Factor Library) they have subscriptions for, going back to August 31, 2021,
     - QFL - Quant Factor Library (Factor Family & Factor Groups) packages they have subscriptions for, going back to January 01, 1995.
     
     Additional parameters are available to filter requests to get the exact files users are looking for.
     
     QFL data is delivered through Content API & Bulk Data API (SDF API)
     - Content API : Provides direct access to FactSet-hosted QFL data.  Suitable for interactive, ad hoc QFL requests.  Constraints on large extracts.  Costs are based on consumption, i.e. more calls can result in more costs.
     - Bulk Data API : Provides access to download locations of zip files for client download. Suitable for production processes within a client environment. Cost is based on the use case and fixed unless scope changes (same as other SDFs).
servers:
  - url: https://api.factset.com/bulk-documents/sdf/v1
paths:
  /list-schemas:
    get:
      summary: Factset schemas
      tags:
        - List Schemas
      operationId: get-v1-list-schemas
      description: >-
        <a
        href=https://api.factset.com/bulk-documents/sdf/v1/list-schemas>List-Schemas</a>
        helper end point provides the list of schemas subscribed by the client
        and their corresponding sequences if no query parameters are passed in
        the request.

         If schema & sequence number (version number of schema) are passed in the request, this endpoint provides a downloadable presigned url containing the schema information.
      parameters:
        - $ref: '#/components/parameters/schema'
        - $ref: '#/components/parameters/sequence'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSchemas'
              examples:
                list-schema200ResponseExample:
                  $ref: '#/components/examples/list-schema_200ResponseExample'
                list-schema200ResponseExample2:
                  $ref: '#/components/examples/list-schema_200ResponseExample2'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-schema_400Response'
              examples:
                list_schema400ResponseExample:
                  $ref: '#/components/examples/list-schema_400ResponseExample'
  /list-files:
    get:
      tags:
        - List Files
      operationId: get-v1-list-files
      description: >
        <a
        href=https://api.factset.com/bulk-documents/sdf/v1/list-files>List-Files</a>
        end point provides the delta & full files in a reverse chronological
        order by default for all the schemas & bundles subscribed by the client


         QFL:-
           - In case of QFL, <a href=https://api.factset.com/bulk-documents/sdf/v1/list-files>List-Files</a> end point provides the "Historical & Year to Date (YTD)" data in a reverse chronological order by default for all the factor families & groups subscribed to by the user</p> Provides "full files" only for historical bundles[data available from 1995 to previous year], "full & delta files" for YTD bundles[data available for current year]
           
           If startDate and endDate parameters are not specified in the request, this endpoint returns past 10 days data by default.
      parameters:
        - $ref: '#/components/parameters/schema'
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/_paginationLimit'
        - $ref: '#/components/parameters/_paginationOffset'
        - $ref: '#/components/parameters/_sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-files_200Response'
              examples:
                default200ResponseExample:
                  $ref: '#/components/examples/list-files_200ResponseExample'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list-files_400Response'
              examples:
                default400ReponseExample:
                  $ref: '#/components/examples/list-files_400ResponseExample'
components:
  parameters:
    schema:
      name: schema
      in: query
      description: |-
        schema name</p> </p> **Example: acta_v1, fgp_v1, yn_v1**

        QFL:- To query QFL data, please use value:   **qfl_v1** 
      required: false
      schema:
        type: string
    sequence:
      name: sequence
      in: query
      description: >-
        Version number of a schema


        Please enter the sequence number associated with the schema passed in
        the request

        **Example: "8" from acta_v1: [8],**


        QFL:- Enter the sequence number associated with the qfl schema 


        **Note:** Please pass sequence parameter only while passing the schema
        parameter in the request
      required: false
      schema:
        type: integer
    bundle:
      name: bundle
      in: query
      description: >-
        bundle name</p> If this parameter is not passed in the request, all the
        bundles a client is subscribed to are returned.


        QFL:-

        - For QFL its the factor group name

        - If this parameter is not passed in the request, all the the factor
        families & factor groups subscribed to by the user are returned. -
        Supports comma separated list of multiple factor groups
      required: false
      schema:
        type: string
    type:
      name: type
      in: query
      description: >-
        file type = Full or Delta</p> Full files are weekly files generated
        every weekend (Saturday). **The date range should include weekend dates
        if requesting for "Full" files**


        QFL:- In case of QFL we have

        - Historical files (1995 to previous year)- Always "Full" . A "Full"
        file is generated for each year

        - For YTD (Current year)- "Full" files are weekly files generated every
        weekend (Saturday). The date range should include weekend dates if
        requesting for "Full" files
      required: false
      schema:
        type: string
        enum:
          - full
          - delta
    startDate:
      name: startDate
      in: query
      description: >-
        The earliest date of the feed file the API should fetch for based on the
        fileTimestamp.</p>



        - If schema parameter is not specified in the request, then data
        requested should be in batches of 10days or less**(Date range should be
        less than or equal to 10)**

        - If the schema parameter is specified in the request, date range can be
        greater than 10 days

        - If startDate and endDate parameters are not specified in the request,
        this endpoint returns past 10 days data by default.

        - startDate can be absolute- YYYY-MM-DD or relative:-  -1 for yesterday


        QFL:- In case of QFL

        - Historical files available from 1995-01-01 to 2021-12-31. YTD files
        are current year files.
      required: false
      schema:
        type: string
    endDate:
      name: endDate
      in: query
      description: >-
        The latest date of the feed file the API should fetch for based on the
        fileTimestamp


        If startDate and endDate parameters are not specified in the request,
        this endpoint returns past 10 days data by default.


        endDate can be in absolute- YYYY-MM-DD or relative date:- 0 for today
      required: false
      schema:
        type: string
    _paginationLimit:
      name: _paginationLimit
      in: query
      description: >-
        Specifies the number of results to return per page. Default is 20 &
        Maximum is 500 results per page
      required: false
      schema:
        type: integer
        default: 20
        maximum: 500
    _paginationOffset:
      name: _paginationOffset
      in: query
      description: >-
        Specifies the starting point for pagination. This parameter is used to
        identify the beginning of next set of results
      required: false
      schema:
        type: integer
        default: 0
    _sort:
      name: _sort
      in: query
      description: >-
        Enables to get the data in ascending or descending order based on
        startTime. Results are in reverse chronological order if this parameter
        is not used
      required: false
      schema:
        type: string
        enum:
          - startDate
  schemas:
    ListSchemas:
      title: ListSchemas
      description: List Of Schemas
      anyOf:
        - $ref: '#/components/schemas/SchemaList'
        - $ref: '#/components/schemas/SchemaDetails'
    SchemaList:
      title: SchemaList
      description: Schema List Object
      type: object
      additionalProperties:
        description: Name of schema with the sequence number (version number) in the value.
        type: array
        items:
          type: string
    SchemaDetails:
      type: object
      properties:
        schema:
          description: schema name
          type: string
        sequence:
          description: version number of the schema
          type: integer
        url:
          description: pre-signed downloadable url containing the information of the schema
          type: string
        timestamp:
          description: time stamp of when the schema sequence was last updated
          type: string
    list-schema_400Response:
      properties:
        id:
          description: request id
          type: string
        error_message:
          description: message describing the error
          type: string
    list-files_200Response:
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/dataresponseitems'
        meta:
          type: object
          properties:
            pagination:
              $ref: '#/components/schemas/pagination'
            partial:
              $ref: '#/components/schemas/partial'
    list-files_400Response:
      properties:
        id:
          description: request id
          type: string
        error_message:
          description: message describing the error
          type: string
    dataresponseitems:
      description: Array of data objects
      type: object
      properties:
        type:
          description: file type, full or delta
          type: string
        bundle:
          description: |-
            bundle name

            QFL:- For QFL its Factor Group name
          type: string
        schema:
          description: |-
            schema name

            QFL:- In case of QFL its always qfl_v1
          type: string
        sequence:
          description: full or delta file sequence
          type: string
        related_bundles:
          description: bundles related to the sequence number
          type: array
          items:
            type: object
            properties:
              bundle:
                type: string
              sequence:
                type: string
        timestamp:
          description: time stamp of when the bundle was generated
          type: string
        url:
          description: pre-signed downloadable url, containing the bundle information
          type: string
        fileSize:
          description: file size of the particular bundle
          type: string
    meta:
      title: meta
      description: Array of metadata objects
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/pagination'
        partial:
          $ref: '#/components/schemas/partial'
    pagination:
      title: paginationobjects
      description: List of pagination objects
      type: object
      properties:
        total:
          description: Total number of files the API returns for a particular query
          type: integer
        is EstimatedTotal:
          description: >-
            Boolean value that represents whether the total count of files
            returned is exact or an estimate. This is defaulted to  False as the
            API should always return the exact count
          type: boolean
        limit:
          description: Number of results returned per page
          type: integer
        offset:
          description: >-
            The flag indicating the position in the results array if additional
            results are available beyond the default value or the value in
            paginationLimit parameter (if used). This value is passed in the
            _paginationOffset parameter to retreieve subsequent results
          type: integer
    partial:
      title: isPartialobject
      description: >-
        If the value is true, it indicates additional results are available.
        False represents that this is the last set of results for this request.
      type: object
      properties:
        isPartial:
          type: boolean
  examples:
    list-schema_200ResponseExample2:
      summary: No Parameters Response
      value:
        acta_v1:
          - '8'
        actr_v1:
          - '2'
        qfl_v1:
          - '2'
    list-schema_200ResponseExample:
      summary: Sample Response
      value:
        schema: acta_v1
        sequence: 8
        url: >-
          https://fdss3-bulk-data-delivery-sdf.s3.amazonaws.com/schema/acta_v1/8/2020-05-28_14_18_33.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA4NAFRGHDMSAGCE52%2F20210511%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210511T170435Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luX2VjECIaCXVzLWVhc3QtMSJIMEYCIQD1He0st1G1qElczFiEEG0DVpLHRkTfIyCgA9pUbHmT4wIhAPyz46DpoaSZDfmk%2FZqbG7xUZjZjDyCbr5uBRw5jlz1JKtkBCKr%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEQARoMODUyNTYyNjIwODcwIgzHhlGrM5TOWg50o9IqrQGOySsSusfChhxaGUj7dfJDMdnJBOJtm6O5pAnVMnzuHhyr%2FLg69QHy%2BmxSO6SdqykHRjuLMnUeNgQ34n75gaLQDe7B%2Bsw9jSZV3NI6O6B2G4Gjga4X7%2Fm1OlKbStb0CgTVjYTjSI4vIMMn1jKmGZvosl9ZSJgpEbeYk5kKG4Kmr%2FXDGbn4C0ZKXbdnWY4yZCaZitNAkJ74hQSxlk7DWBrTKY1QZUT7WBvd3hRXRTCY8uqEBjrfAdcXYNIJmuyJRel22QcGZ24xPyUXJyW9%2B3vbmDQx3QHLyyHZq%2BbKGKt0sphxhfna%2Bu9qdApKhkBbk1N1%2Bv%2FXLvItRG5Y38ZPpy4gj6hgs6h5%2Buay1Esb32f4083L8uBL26NuUDg09odjE6sBpuqkJoTiBMXaKdlHbU0GfrOli2dK46rhDmY6m1jbF2Najd1v5rbDW%2FPRzYnpM638paqbwUev%2FcLgGvRI%2FXuWoNH%2FfhXFCZf9G20BGWWyhuOoq0%2BSL0a4BQkZXHNjiCXQrysuQtonI4NF%2BD%2FfwZtPuD%2BEsJg%3D&X-Amz-Signature=58517963bbb5b77b481ce68df391c7e29166ac330c552c79f4df68cfdd0585ab
        timestamp: '2020-05-28 14:18:33'
    list-schema_400ResponseExample:
      summary: Sample Response
      value:
        id: xxxx-xxxx-xxxx-xxxx                     **Example**
        error_message: 'parameterError:schema_name : Not a valid schema.'
    list-files_200ResponseExample:
      summary: Sample Response
      value:
        data:
          - type: delta
            bundle: fgp_ca_events_am_v1
            schema: fgp_v1
            sequence: '555'
            related_bundles:
              - bundle: fgp_ca_events_ap_v1
                sequence: '523'
              - bundle: fgp_ca_events_eu_v1
                sequence: '576'
            timestamp: '2021-04-22T19:59:53Z'
            url: >-
              https://fdss3-sdf-publish-prod.s3.amazonaws.com/prod/04/22/22A8B666-A3A5-11EB-94AA-8CA2536ACF03?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA4NAFRGHDJ4GMEZEZ%2F20210512%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210512T172835Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEDoaCXVzLWVhc3QtMSJHMEUCIQCU337Iqg7hGI84ohliykGkMwyuxkv5ZepMXlOkjFuT0gIgAUfMuxk0Ue7nbo7WdhclIUaUe6dlwHso2lDHKXzbUQkq2QEIw%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARABGgw4NTI1NjI2MjA4NzAiDFL7Kj2AKk4MnRzXJiqtAXmh3NCgz9Z%2F%2FgI6ARqtFaKmP%2BpWfojZI6c%2FSLDceZE4q0qRKVU5Nh%2Fk5cH%2FC4E8acrjupEmeaLIsUEm%2F%2F7W1kla6nJ%2B%2Bwx9ViaOBfbP1wjG6dDY%2BMwalM3lq1bCpZbDFvOt1uUMBSUgJd5UJbdvMVtivXkkzKh%2B2dvt0fMHIgIMUnJzsSbFcLgKnS3lYEp5y%2B0622wrK90RIfw7Q8rN6W9OoFJ4UiCJJpE9OH5ZMNGd8IQGOuABNzZAf%2FHtTM9NmNIQwLpMSivjlhLl6chrPWvt4T6OQMN%2B6yaBz%2F%2BOig3Zc29HuR45dZ35QPd30mswAX0Md637pBkB7vjkakp70fbvIlGwsJ0vPq01a3SVfS0wsW6MRgGNdxJbItuZ9XKrV2SRSZFHntOH1BHHHtbR5hpSUg5HTpasOT%2BWNXHJKjTXVjjWmt3t3ATOUOcFluxt6UL5eg2hBY8UsAbgs2zxzRlzeEJU%2Bnq9%2BQc9TSE9Ia%2BOqKWSVUs6qQ0zyZ5G9OL8hs%2B9pdgQemrquBKXZ9FBHiEyr38OY0c%3D&X-Amz-Signature=e76cf34978304834e809144f126830c2fe65cb8301e67659fb281eb4734de3b8
            fileSize: 25.5MB
        meta:
          pagination:
            total: 256
            isEstimatedTotal: false
            limit: 20
            offset: 20
          partial:
            isPartial: true
    list-files_400ResponseExample:
      summary: Sample Response
      value:
        data:
          id: xxx
          error_message: >-
            parameterError:sequence must be an int and be within specified
            limits
        meta:
          pagination:
            total: 0
            isEstimatedTotal: false
            limit: 20
            offset: 20
          partial:
            isPartial: false
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
tags:
  - name: List Files
  - name: List Schemas