openapi: 3.0.0
info:
  version: 1.0.1
  title: Factset Classifications API
  contact:
    name: FactSet Research Systems
    email: api@factset.com
  description: >
    The Classifications API gives access to various Industry Classifications for
    a given list of securities. Beginning first with GICS Direct, the service
    will then expand to offering NAICS, SIC, RBICS, and more. 
servers:
  - url: https://api.factset.com/content
    description: Production
security:
  - BasicAuth: []
tags:
  - name: Classifications
paths:
  /classifications/v1/gics:
    get:
      tags:
        - Classifications
      summary: Factset Gets the GICS Direct Classifications
      operationId: getGics
      description: >
        Gets the **Global Industry Classification Standard ("GICS")** Sectors,
        Industry Group, Industry, and Sub-Industry Names and Numbers for a
        requested list of ids and date range. All economic sectors have a
        two-digit identification code, all industry groups have a four-digit
        identification code, all industries have a six-digit identification
        code, and all sub-industries have an eight-digit identification code. To
        access the complete GICS structure and definitions, visit the [MSCI
        GICS](https://www.msci.com/gics) or [S&P
        GICS](https://www.spglobal.com/spdji/en/landing/topic/gics/) home pages.
        Coverage includes over 37,000 securities.

        *Licensing for GICS Classifications, Regions, and History is required in
        addition to FactSet API license. Reach out to your FactSet Account Team
        for assistance.*
      parameters:
        - $ref: '#/components/parameters/ids'
        - $ref: '#/components/parameters/startDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/frequency'
        - $ref: '#/components/parameters/calendar'
      responses:
        '200':
          description: GICS Response Object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gicsResponse'
              examples:
                Multiple IDs as of latest month end:
                  $ref: '#/components/examples/gicsMultipleExample'
                Security with GICS Change:
                  $ref: '#/components/examples/gicsChangeExample'
        '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:
      tags:
        - Classifications
      summary: Factset Returns the GICS classifications for the requested 'ids' and date range.
      description: >
        Gets the **Global Industry Classification Standard ("GICS")** Sectors,
        Industry Group, Industry, and Sub-Industry Names and Numbers for a
        requested list of ids and date range. All economic sectors have a
        two-digit identification code, all industry groups have a four-digit
        identification code, all industries have a six-digit identification
        code, and all sub-industries have an eight-digit identification code. To
        access the complete GICS structure and definitions, visit the [MSCI
        GICS](https://www.msci.com/gics) or [S&P
        GICS](https://www.spglobal.com/spdji/en/landing/topic/gics/) home pages.
        Coverage includes over 37,000 securities.

        *Licensing for GICS Classifications, Regions, and History is required in
        addition to FactSet API license. Reach out to your FactSet Account Team
        for assistance.*
      operationId: postGics
      requestBody:
        required: true
        description: Requests GICS Classifications for the given identifier and date range.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/gicsRequest'
      responses:
        '200':
          description: GICS Direct Response Items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gicsResponse'
              examples:
                Multiple IDs as of latest month end:
                  $ref: '#/components/examples/gicsMultipleExample'
                Security with GICS Change:
                  $ref: '#/components/examples/gicsChangeExample'
        '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'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
  parameters:
    ids:
      name: ids
      in: query
      required: true
      explode: false
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 1000
      description: >
        The requested list of security identifiers. Accepted ID types include
        Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids.
        <p>***ids limit** =  1000 per request*</p> *<p>Make note, GET Method URL
        request lines are also limited to a total length of 8192 bytes (8KB). In
        cases where the service allows for thousands of ids, which may 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>*
    startDate:
      name: startDate
      in: query
      required: false
      schema:
        type: string
      description: Requested start date expressed in YYYY-MM-DD format.
    endDate:
      name: endDate
      in: query
      required: false
      schema:
        type: string
      description: Requested End Date for Range expressed in YYYY-MM-DD format.
    currency:
      name: currency
      in: query
      required: false
      schema:
        type: string
      description: Currency for response.
    frequency:
      name: frequency
      in: query
      schema:
        type: string
        enum:
          - D
          - W
          - M
          - AM
          - CQ
          - AY
          - CY
        default: M
      description: |
        Controls the display frequency of the data returned.
          * **D** = Daily
          * **W** = Weekly, based on the last day of the week of the start date.
          * **M** = Monthly, based on the last trading day of the month.
          * **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.).
          * **CQ** = Quarterly based on the last trading day of the calendar quarter (March, June, September, or December).
          * **AY** = Actual Annual, based on the start date.
          * **CY** = Calendar Annual, based on the last trading day of the calendar year.
    calendar:
      name: calendar
      in: query
      schema:
        type: string
        enum:
          - FIVEDAY
          - SEVENDAY
        default: FIVEDAY
      description: Calendar of data returned. SEVENDAY includes weekends.
  schemas:
    gicsRequest:
      type: object
      title: GICS POST Request Model
      properties:
        ids:
          $ref: '#/components/schemas/ids'
        startDate:
          $ref: '#/components/schemas/startDate'
        endDate:
          $ref: '#/components/schemas/endDate'
        frequency:
          $ref: '#/components/schemas/frequency'
        calendar:
          $ref: '#/components/schemas/calendar'
      required:
        - ids
    gicsResponse:
      title: GICS Response
      type: object
      properties:
        data:
          description: |
            Array of GICS Objects, representing all requested ids and dates.
          type: array
          items:
            $ref: '#/components/schemas/gics'
    gics:
      title: GICS Object
      type: object
      properties:
        fsymId:
          type: string
          description: >-
            FactSet Entity Identifier by default, otherwise returns FactSet
            Regional Identifier. This is a six alpha-numeric characters,
            excluding vowels, with an -E suffix (XXXXXX-E).
          example: 0FPWZZ-E
        date:
          description: Date in YYYY-MM-DD for the classification record from GICS Direct
          type: string
          format: date
          example: '2020-10-30'
        gicsSectorName:
          description: GICS Sector Name in Proper Format.
          type: string
          example: Communications Services
        gicsSectorNumber:
          description: GICS Sector Number
          type: string
          example: '50'
        gicsIndustryGroupName:
          description: GICS Industry Group Name in Proper Format.
          type: string
          example: Media & Entertainment
        gicsIndustryGroupNumber:
          description: GICS Industry Group Number
          type: string
          example: '5020'
        gicsIndustryName:
          description: GICS Industry Name in Proper Format.
          type: string
          example: Interactive Media & Services
        gicsIndustryNumber:
          description: GICS Industry Number
          type: string
          example: '502030'
        gicsSubIndustryName:
          description: GICS Sub-Industry Name in Proper Format.
          type: string
          example: Interactive Media & Services
        gicsSubIndustryNumber:
          description: GICS Industry Number.
          type: string
          example: '50203010'
        requestId:
          type: string
          description: Identifier specified in the request
          example: SPY-US
    ids:
      title: Security Ids
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 1000
      description: >
        The requested list of security identifiers. Accepted ID types include
        Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids.
        <p>***ids limit** =  1000 per request*</p> *<p>Make note, GET Method URL
        request lines are also limited to a total length of 8192 bytes (8KB). In
        cases where the service allows for thousands of ids, which may 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>*
      example:
        - AAPL-US
    startDate:
      title: Start Date
      type: string
      description: Requested start date expressed in YYYY-MM-DD format.
      example: '2018-12-31'
    endDate:
      title: End Date
      type: string
      description: Requested end date for Range expressed in YYYY-MM-DD format.
      example: '2019-12-31'
    frequency:
      title: Frequency
      type: string
      enum:
        - D
        - W
        - M
        - AM
        - CQ
        - AY
        - CY
      default: M
      description: |
        Controls the display frequency of the data returned.
          * **D** = Daily
          * **W** = Weekly, based on the last day of the week of the start date.
          * **M** = Monthly, based on the last trading day of the month.
          * **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.). 
          * **CQ** = Quarterly based on the last trading day of the calendar quarter (March, June, September, or December).
          * **AY** = Actual Annual, based on the start date.
          * **CY** = Calendar Annual, based on the last trading day of the calendar year.
      example: M
    calendar:
      title: Calendar
      type: string
      enum:
        - FIVEDAY
        - SEVENDAY
      default: FIVEDAY
      description: Calendar of data returned. SEVENDAY includes weekends.
      example: FIVEDAY
    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: /classifications/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
  responses:
    '400':
      description: >-
        Bad Request. This can occur for several reasons. Please review the
        "message" for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/badRequestDateFormat'
            Bad Request - Missing Required Parameter:
              $ref: '#/components/examples/badRequestRequiredParameter'
            Bad Request - Future Date:
              $ref: '#/components/examples/badRequestFutureDate'
            Bad Request - Invalid Parameter:
              $ref: '#/components/examples/badRequestInvalidParameters'
            Bad Request - Malformed JSON:
              $ref: '#/components/examples/badRequestMalformedJSON'
            Bad Request - Read Timeout:
              $ref: '#/components/examples/badRequestReadTimeout'
    '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'
    '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'
    '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'
    '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'
  examples:
    gicsMultipleExample:
      summary: Fetching GICS Direct Classifications for two securities
      description: >-
        Fetching GICS Direct Classifications for XOM and APPL as of latest
        completed period.
      value:
        data:
          - date: '2020-10-30'
            fsymId: 0FPWZZ-E
            gicsIndustryGroupName: Media & Entertainment
            gicsIndustryGroupNumber: '5020'
            gicsIndustryName: Interactive Media & Services
            gicsIndustryNumber: '502030'
            gicsSectorName: Communication Services
            gicsSectorNumber: '50'
            gicsSubIndustryName: Interactive Media & Services
            gicsSubindustryNumber: '50203010'
            requestId: GOOGL
          - date: '2020-10-30'
            fsymId: 002Q0G-E
            gicsIndustryGroupName: Energy
            gicsIndustryGroupNumber: '1010'
            gicsIndustryName: Oil Gas & Consumable Fuels
            gicsIndustryNumber: '101020'
            gicsSectorName: Energy
            gicsSectorNumber: '10'
            gicsSubIndustryName: Integrated Oil & Gas
            gicsSubindustryNumber: '10102010'
            requestId: XOM
    gicsChangeExample:
      summary: Fetching GICS Classifications for Security with Changes
      description: >-
        Fetching Acadia Realty Trust (AKR-US) in 2016 over period in which
        classifications changed from Financials to Real Estate.
      value:
        data:
          - date: '2016-08-31'
            fsymId: 00263C-E
            gicsIndustryGroupName: Real Estate
            gicsIndustryGroupNumber: '4040'
            gicsIndustryName: Real Estate Investment Trusts (REITs)
            gicsIndustryNumber: '404020'
            gicsSectorName: Financials
            gicsSectorNumber: '40'
            gicsSubIndustryName: Retail REITs
            gicsSubindustryNumber: '40402060'
            requestId: AKR-US
          - date: '2016-09-30'
            fsymId: 00263C-E
            gicsIndustryGroupName: Real Estate
            gicsIndustryGroupNumber: '6010'
            gicsIndustryName: Equity Real Estate Investment Trusts (REITs)
            gicsIndustryNumber: '601010'
            gicsSectorName: Real Estate
            gicsSectorNumber: '60'
            gicsSubIndustryName: Retail REITs
            gicsSubindustryNumber: '60101070'
            requestId: AKR-US
    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: /classifications/v1/{endpoint}
        message: >-
          The date parameter 'startDate' must be in the following date format:
          YYYY-MM-DD
        subErrors:
    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: /classifications/v1/{endpoint}
        message: The parameter 'ids' is required and may not be empty.
        subErrors:
    badRequestFutureDate:
      summary: Bad Request - Future Date
      description: >-
        This error message occurs when a future date is requested in the
        startDate and endDate parameters. Please revise your request to include
        dates as of today's current date or any prior historical date.
      value:
        status: Bad Request
        timestamp: '2020-06-12 15:52:48.091'
        path: /classifications/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:
    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: /classifications/v1/{endpoint}
        message: >-
          Invalid Parameter (s): fakeParameterName1 fakeParameterName2. Please
          modify your request to use parameters outlined in the specification
          for this endpoint.
        subErrors:
    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: /classifications/v1/{endpoint}
        message: Malformed JSON Request
        subErrors:
    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: /classifications/v1/{endpoint}
        message: The request took too long. Try again with a smaller request.
        subErrors:
    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: /classifications/v1/{endpoint}
        message: User Authentication Failed.
        subErrors:
    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: /classifications/v1/{endpoint}
        message: >-
          USERNAME-SERIAL does not have permission to use
          /classifications/v1/{endpoint}
        subErrors:
    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: /classifications/v1/{endpoint}
        message: >-
          text/html media type is not supported. Supported media types are
          application/json
        subErrors:
    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: /classifications/v1/{endpoint}
        message: Error writing JSON output
        subErrors:
    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: /classifications/v1/{endpoint}
        message: Unexpected error
        subErrors: