openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Annualized 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: Annualized
paths:
  /factset-global-prices/v1/annualized-dividends:
    get:
      tags:
      - Annualized
      summary: Factset Gets Indicated Annualized Dividend Information.
      operationId: getannualizedDividends
      description: 'Gets the Annualized dividend of the latest reported dividend.

        The annualized dividend calculations does not involve cancelled dividends.

        '
      parameters:
      - $ref: '#/components/parameters/idsBatchMax2000'
      - $ref: '#/components/parameters/currency'
      - $ref: '#/components/parameters/batch'
      responses:
        '200':
          description: Array of annualized dividend information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/annualizedDividendResponse'
        '202':
          description: Batch request has been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Request Accepted:
                  $ref: '#/components/examples/BatchStatusAcceptedResponse'
          headers:
            Location:
              description: Path to Batch Request status.
              schema:
                type: string
              example: batch-status?id=2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
        '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:
      tags:
      - Annualized
      summary: Factset Gets Indicated Annualized Dividend Information.
      description: Gets the Annualized dividend of the latest reported dividend. The annualized dividend calculations does not involve cancelled dividends.
      operationId: getannualizedDividendsForList
      requestBody:
        required: true
        description: Request object for `Annualized Response`.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/annualizedDividendsRequest'
      responses:
        '200':
          description: Array of security prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/annualizedDividendResponse'
        '202':
          description: Batch request has been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatusResponse'
              examples:
                Batch Request Accepted:
                  $ref: '#/components/examples/BatchStatusAcceptedResponse'
          headers:
            Location:
              description: Path to Batch Request status.
              schema:
                type: string
              example: batch-status?id=2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    batchErrorObject:
      type: object
      nullable: true
      properties:
        id:
          description: A UUID for this particular occurrence of the problem.
          type: string
          nullable: true
          example: adb01824-252f-4420-b0c6-35a1e3507ef5
        code:
          description: status
          type: string
          nullable: true
          example: GenericError
        links:
          description: The Endpoint path {package}/version/{endpoint}
          type: object
          properties:
            about:
              description: details.
              type: string
              example: /factset-global-prices/v1/{endpoint}
          example: example_value
        title:
          description: The plain text error message
          type: string
          nullable: true
          example: Validation Error
    batch:
      description: 'Enables the ability to asynchronously "batch" the request, supporting a long-running request for up to 20 minutes. Upon requesting batch=Y, the service will respond back with an HTTP Status Code of 202. Once a batch request is submitted, use batch status to see if the job has been completed. Once completed, retrieve the results of the request via batch-result. When using Batch, ids limit is increased to 10000 ids per request, though limits on query string via GET method still apply. It''s advised to submit large lists of ids via POST method. Please note that the number of unique currencies present in the requested ids is limited to 50 per request.

        '
      type: string
      enum:
      - Y
      - N
      default: N
    idsBatchMax10000:
      type: array
      items:
        type: string
      description: "The requested list of security identifiers. Accepted ID types include Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids. \n<p>ids limit =  1000 per non-batch request / 10000 per batch request for a single day and 50 per multi-day request</p>\n"
      example:
      - FDS-US
    BatchStatus:
      title: Batch Status
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: the id of batch request.
          example: abc123
        startTime:
          type: string
          format: date-time
          description: Time when the batch request is started. This is in Eastern Time Zone. The date-time format is expressed as [YYYY-MM-DD]T[HH:MM:SSS], following ISO 8601.
          example: '2026-01-15T10:30:00Z'
        endTime:
          type: string
          format: date-time
          description: Time when the batch request is ended. This is in Eastern Time Zone. The date-time format is expressed as [YYYY-MM-DD]T[HH:MM:SSS], following ISO 8601.
          nullable: true
          example: '2026-01-15T10:30:00Z'
        status:
          type: string
          enum:
          - queued
          - executing
          - created
          - failed
          example: queued
        error:
          $ref: '#/components/schemas/batchErrorObject'
    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-global-prices/v1/prices
        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
    annualizedDividendsRequest:
      title: Annualized Dividends Request Body
      description: Annualized Dividends Request Body
      type: object
      properties:
        ids:
          $ref: '#/components/schemas/idsBatchMax10000'
        currency:
          $ref: '#/components/schemas/requestCurrency'
        batch:
          $ref: '#/components/schemas/batch'
      required:
      - ids
    BatchStatusResponse:
      title: Batch Status Response
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BatchStatus'
    requestCurrency:
      title: Request Currency
      type: string
      description: Currency code for adjusting prices. Default is Local. For a list of currency ISO codes, visit [Online Assistant Page 1470](https://oa.apps.factset.com/pages/1470).
      example: USD
    annualizedDividendResponse:
      type: object
      title: Annualized Dividends Response
      properties:
        data:
          description: Array of Annualized Dividends Objects
          type: array
          items:
            $ref: '#/components/schemas/annualizedDividendsObject'
          example: []
    annualizedDividendsObject:
      title: Annualized Dividends Object
      type: object
      properties:
        fsymId:
          description: Factset Regional Security Identifier. Six alpha-numeric characters, excluding vowels, with an -R suffix (XXXXXX-R). Identifies the security's best regional security data series per currency. For equities, all primary listings per region and currency are allocated a regional-level permanent identifier. The regional-level permanent identifier will be available once a SEDOL representing the region/currency has been allocated and the identifiers are on FactSet.
          type: string
          example: SJY281-R
          x-fds-dh: REGIONAL_FDS_ID
          nullable: true
        eventId:
          description: FactSet identifier that uniquely identifies the Event.
          type: string
          example: JTHPFN-A
          x-fds-dh: EVENT_ID
          nullable: true
        effectiveDate:
          description: Effective Date or Ex-Date of Annualized Dividend in YYYY-MM-DD format.
          type: string
          example: '2022-03-11T00:00:00.000Z'
          x-fds-dh: IAD_EXDATE
          nullable: true
        iadDefTradingAdj:
          description: Annualized Dividend value in the trading currency. The value is adjusted for splits
          type: number
          format: float
          x-fds-dh: IAD_DEF_SPLIT
          example: 0.7584434
          nullable: true
        currency:
          description: 'Currency ISO code associated with the annualized dividends.For more details, visit [Online Assistant Page #1470](https://oa.apps.factset.com/pages/1470).'
          type: string
          example: USD
          x-fds-dh: IAD_DEF_CURR_ISO
          nullable: true
        requestId:
          description: Identifier that was used for the request.
          type: string
          example: AAPL-US
  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-global-prices/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-global-prices/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-global-prices/v1/{endpoint}
        message: Error writing JSON output
        subErrors: null
    BatchStatusAcceptedResponse:
      description: Batch Status Accepted Response
      value:
        data:
          id: 2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
          status: queued
          startTime: '2021-06-29T18:34:52.168Z'
          endTime: null
          error: 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-global-prices/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-global-prices/v1/{endpoint}
        message: Unexpected error
        subErrors: null
    badRequestReadTimeout:
      summary: Bad Request - Read Timeout
      description: This error may be returned if it takes more than 29 seconds to hear back from the data fetch service.
      value:
        status: Bad Request
        timestamp: '2019-11-04 16:18:38.949'
        path: /factset-global-prices/v1/{endpoint}
        message: The request took too long. Try again with a smaller request.
        subErrors: null
    badRequestFutureDate:
      summary: Bad Request - Future Date
      description: This error message occurs when a future date is requested in the 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: /factset-global-prices/v1/{endpoint}
        message: The use of future dates is not applicable in this endpoint. Please revise your request to include dates up to today's current date.
        subErrors: null
    forbidden:
      summary: Forbidden
      description: The USERNAME-SERIAL attempted to request the endpoint 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-global-prices/v1/{endpoint}
        message: USERNAME-SERIAL does not have permission to use /factset-global-prices/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-global-prices/v1/{endpoint}
        message: User Authentication Failed.
        subErrors: null
    badRequestMalformedJSON:
      summary: Bad Request - Malformed JSON Request
      description: This error may be returned when the request body is specified as JSON, but is not in proper JSON format.
      value:
        status: Bad Request
        timestamp: '2019-11-05 09:48:29.18'
        path: /factset-global-prices/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-global-prices/v1/{endpoint}
        message: The parameter 'ids' is required and may not be empty.
        subErrors: null
  responses:
    '401':
      description: Unauthenticated USERNAME-SERIAL. Ensure you are logged in and have successfully generated an API KEY for the IP range you are connecting from. For more help, select the **Report Issue** in the top right corner of this Developer Portal specification card and choose Connectivity 401 or 403 Responses.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/unauthenticated'
    '415':
      description: Unsupported Media Type. This error may be returned when the caller sends a resource in a format that is not accepted by the server. This can be fixed by ensuring that Content-Type header is set to the correct value. In this instance, "application/json" would be the appropriate value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - 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'
    '500':
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Internal Server Error - Not Writable:
              $ref: '#/components/examples/notWritable'
            Internal Server Error - General Exception:
              $ref: '#/components/examples/generalException'
    '400':
      description: Bad Request. This can occur for several reasons. Please review the "message" for more details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          examples:
            Bad Request - Date Format:
              $ref: '#/components/examples/badRequestDateFormat'
            Bad Request - Missing Required Parameter:
              $ref: '#/components/examples/badRequestRequiredParameter'
            Bad Request - Future Date:
              $ref: '#/components/examples/badRequestFutureDate'
            Bad Request - Invalid Parameter:
              $ref: '#/components/examples/badRequestInvalidParameters'
            Bad Request - Malformed JSON:
              $ref: '#/components/examples/badRequestMalformedJSON'
            Bad Request - Read Timeout:
              $ref: '#/components/examples/badRequestReadTimeout'
  parameters:
    currency:
      name: currency
      in: query
      schema:
        type: string
      description: Currency code for adjusting prices. Default is Local. For a list of currency ISO codes, visit [Online Assistant Page 1470](https://oa.apps.factset.com/pages/1470).
      example: USD
    batch:
      name: batch
      in: query
      description: 'Enables the ability to asynchronously "batch" the request, supporting a long-running request for up to 20 minutes. Upon requesting batch=Y, the service will respond with an HTTP Status Code of 202.

        Once a batch request is submitted, use batch status to see if the job has been completed. Once completed, retrieve the results of the request via batch-result. When using Batch, ids limit is increased to 10000 ids per request, though limits on query string via GET method still apply. It''s advised to submit large lists of ids via POST method.

        <B>Please note that the number of unique currencies present in the requested ids is limited to 50 per request.</B>

        '
      schema:
        type: string
        enum:
        - Y
        - N
        default: N
    idsBatchMax2000:
      name: ids
      in: query
      schema:
        type: array
        items:
          type: string
      required: true
      explode: false
      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 non-batch request / 2000 per batch request for a single day and 50 per multi-day 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, it's advised for any requests with large request lines to be requested through the respective "POST" method.</p>*
      examples:
        oneEquityId:
          summary: One Equity Market Identifier
          value:
          - AAPL-USA
        multipleEquityIds:
          summary: Multiple Equity Market Identifiers
          value:
          - FDS-US
          - AAPL-US
          - MSFT-US
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
externalDocs:
  url: https://developer.factset.com/api-catalog/analytics-datastore-api
  description: API Documentation