openapi: 3.0.3
info:
  title: Factset Analytics Datastore About Ratios 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: Ratios
  description: Access pre-calculated financial ratios including profitability, liquidity, growth rates, size, and valuation metrics.
paths:
  /ratios:
    get:
      tags:
      - Ratios
      operationId: getRatios
      summary: Factset Returns Pre-calculated Financial Ratios.
      description: 'Retrieves pre-calculated financial ratios for specified securities. Available ratio subcategories include FINANCIAL, GROWTH_RATE, LIQUIDITY, PROFITABILITY, SIZE, and VALUATION.


        Common ratios include price-to-earnings (FF_PE), return on equity (FF_ROE), debt-to-equity (FF_DEBT_EQUITY), current ratio (FF_CURR_RATIO), and many others.'
      parameters:
      - $ref: '#/components/parameters/ids'
      - $ref: '#/components/parameters/ratioMetrics'
      - $ref: '#/components/parameters/ratioSubcategory'
      - $ref: '#/components/parameters/periodicity'
      - $ref: '#/components/parameters/fiscalPeriodStart'
      - $ref: '#/components/parameters/fiscalPeriodEnd'
      - $ref: '#/components/parameters/currency'
      responses:
        '200':
          description: Ratio data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatiosResponse'
              examples:
                valuationRatios:
                  summary: Valuation ratios for AAPL-US
                  value:
                    data:
                    - requestId: AAPL-US
                      fsymId: MH33D6-R
                      metric: FF_PE
                      periodicity: ANN
                      fiscalPeriod: 0
                      fiscalYear: 2023
                      fiscalEndDate: '2023-09-30'
                      currency: USD
                      value: 29.84
                    - requestId: AAPL-US
                      fsymId: MH33D6-R
                      metric: FF_PBK
                      periodicity: ANN
                      fiscalPeriod: 0
                      fiscalYear: 2023
                      fiscalEndDate: '2023-09-30'
                      currency: USD
                      value: 48.72
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Ratios
      operationId: postRatios
      summary: Factset Returns Pre-calculated Financial Ratios for a List of Identifiers.
      description: Retrieves pre-calculated financial ratios via POST for large identifier sets.
      requestBody:
        required: true
        description: Request object for ratio data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RatiosRequest'
      responses:
        '200':
          description: Ratio data returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatiosResponse'
        '202':
          $ref: '#/components/responses/BatchAccepted'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    ErrorResponse:
      type: object
      title: Error Response
      description: Standard error response wrapper.
      properties:
        errors:
          type: array
          description: An array containing error details.
          items:
            $ref: '#/components/schemas/Error'
          example: []
    RatiosRequest:
      type: object
      title: Ratios Request
      description: Wrapper for ratios request body.
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/RatiosRequestBody'
    FiscalPeriod:
      type: object
      title: Fiscal Period
      description: Fiscal period date range specification. Calendar dates that will fall back to the most recently completed period during resolution.
      properties:
        start:
          type: string
          format: date
          description: The fiscal period start expressed as YYYY-MM-DD.
          examples:
          - '2023-01-01'
        end:
          type: string
          format: date
          description: The fiscal period end expressed as YYYY-MM-DD.
          examples:
          - '2024-01-01'
    RatiosResponse:
      type: object
      title: Ratios Response
      description: Response wrapper containing an array of ratio data items.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Ratio'
          example: []
    BatchStatus:
      type: object
      title: Batch Status
      description: Status information for an asynchronous batch request.
      properties:
        id:
          type: string
          format: uuid
          description: The batch request identifier.
          example: abc123
        startTime:
          type: string
          format: date-time
          description: Time when the batch request started (Eastern Time Zone).
          example: '2026-01-15T10:30:00Z'
        endTime:
          type:
          - string
          - 'null'
          format: date-time
          description: Time when the batch request ended. Null if still processing.
          example: '2026-01-15T10:30:00Z'
        status:
          type: string
          description: Current batch processing status.
          enum:
          - queued
          - executing
          - created
          - failed
          example: queued
        error:
          $ref: '#/components/schemas/BatchError'
    Error:
      type: object
      title: Error
      description: A single error detail object.
      properties:
        id:
          type: string
          description: A UUID for this particular occurrence of the problem.
          examples:
          - adb01824-252f-4420-b0c6-35a1e3507ef5
        code:
          type: string
          description: Error status code description.
          examples:
          - Bad Request
        title:
          type: string
          description: The plain text error message.
          examples:
          - Validation Error
        links:
          type: object
          description: The endpoint path for reference.
          properties:
            about:
              type: string
              description: API path that generated the error.
              examples:
              - /factset-fundamentals/v2/fundamentals
          example: example_value
    RatiosRequestBody:
      type: object
      title: Ratios Request Body
      description: Request parameters for financial ratio data.
      required:
      - ids
      - metrics
      properties:
        ids:
          $ref: '#/components/schemas/SecurityIds'
        metrics:
          $ref: '#/components/schemas/MetricsList'
        subcategory:
          type: string
          description: Ratio subcategory filter.
          enum:
          - FINANCIAL
          - GROWTH_RATE
          - LIQUIDITY
          - PROFITABILITY
          - SIZE
          - VALUATION
          example: FINANCIAL
        periodicity:
          $ref: '#/components/schemas/Periodicity'
        fiscalPeriod:
          $ref: '#/components/schemas/FiscalPeriod'
        currency:
          $ref: '#/components/schemas/Currency'
        batch:
          $ref: '#/components/schemas/BatchFlag'
    Periodicity:
      type: string
      title: Periodicity
      description: Periodicity or frequency of the fiscal periods. ANN = Annual, QTR = Quarterly, SEMI = Semi-Annual, LTM = Last Twelve Months, YTD = Year-to-date. Suffix _R includes restatements.
      enum:
      - ANN
      - ANN_R
      - QTR
      - QTR_R
      - SEMI
      - SEMI_R
      - LTM
      - LTM_R
      - LTMSG
      - LTM_SEMI
      - YTD
      default: ANN
    Ratio:
      type: object
      title: Ratio
      description: A single pre-calculated financial ratio for a security and fiscal period.
      properties:
        requestId:
          type: string
          description: Identifier that was used for the request.
          examples:
          - AAPL-US
        fsymId:
          type:
          - string
          - 'null'
          description: FactSet Regional Security Identifier.
          examples:
          - MH33D6-R
        metric:
          type:
          - string
          - 'null'
          description: The ratio metric identifier.
          examples:
          - FF_PE
        periodicity:
          type:
          - string
          - 'null'
          description: Periodicity of the fiscal period.
          examples:
          - ANN
        fiscalPeriod:
          type:
          - integer
          - 'null'
          description: Fiscal period indicator.
          examples:
          - 0
        fiscalYear:
          type:
          - integer
          - 'null'
          description: Fiscal year in YYYY format.
          examples:
          - 2023
        fiscalEndDate:
          type:
          - string
          - 'null'
          format: date
          description: The normalized date the fiscal period ended.
          examples:
          - '2023-09-30'
        currency:
          type:
          - string
          - 'null'
          description: ISO 4217 currency code.
          examples:
          - USD
        value:
          type:
          - number
          - 'null'
          format: double
          description: The calculated ratio value.
          examples:
          - 29.84
    BatchError:
      type:
      - object
      - 'null'
      title: Batch Error
      description: Error information for a failed batch request.
      properties:
        id:
          type: string
          description: A UUID for this particular occurrence of the problem.
          example: abc123
        code:
          type: string
          description: Error code.
          example: example_value
        title:
          type: string
          description: The plain text error message.
          example: Example Title
    Currency:
      type: string
      title: Currency
      description: ISO 4217 currency code. Use "DOC" for reporting currency. Defaults to LOCAL.
      default: LOCAL
      examples:
      - USD
      - EUR
      - LOCAL
    BatchStatusResponse:
      type: object
      title: Batch Status Response
      description: Wrapper for batch request status.
      properties:
        data:
          $ref: '#/components/schemas/BatchStatus'
    BatchFlag:
      type: string
      title: Batch Flag
      description: Enable asynchronous batch processing. Y = Enable, N = Disable.
      enum:
      - Y
      - N
      default: N
    SecurityIds:
      type: array
      title: Security Identifiers
      description: List of security identifiers. Accepted types include Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids. Limit of 1,000 per non-batch request / 30,000 per batch request.
      items:
        type: string
      minItems: 1
      maxItems: 30000
      examples:
      - - FDS-US
      - - FDS-US
        - AAPL-US
        - MSFT-US
    MetricsList:
      type: array
      title: Metrics List
      description: List of fundamental metric identifiers. Use the /metrics endpoint for a complete catalog of available items.
      items:
        type: string
      minItems: 1
      maxItems: 1600
      examples:
      - - FF_SALES
      - - FF_SALES
        - FF_EPS
        - FF_PE
  responses:
    InternalServerError:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthenticated USERNAME-SERIAL. Ensure you are logged in and have successfully generated an API KEY for the IP range you are connecting from.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: Unsupported Media Type. Ensure that the Content-Type header is set to "application/json".
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request. This can occur for several reasons. Please review the error message for details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The USERNAME-SERIAL attempted to request the endpoint is not authorized to access. Please reach out to FactSet Account Team for assistance with authorization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BatchAccepted:
      description: Batch request has been accepted for processing.
      headers:
        Location:
          description: Path to batch request status endpoint.
          schema:
            type: string
          example: batch-status?id=2df43e85-ea0f-45c6-bf4a-2baf4d1eaa3c
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BatchStatusResponse'
  parameters:
    fiscalPeriodStart:
      name: fiscalPeriodStart
      in: query
      required: false
      description: The fiscal period start expressed as YYYY-MM-DD. Calendar date that will fall back to the most recent completed period during resolution.
      schema:
        type: string
        format: date
        examples:
        - '2023-01-01'
    periodicity:
      name: periodicity
      in: query
      required: false
      description: Periodicity or frequency of the fiscal periods. ANN = Annual Original, ANN_R = Annual Latest (includes restatements), QTR = Quarterly Original, QTR_R = Quarterly Latest, SEMI = Semi-Annual, SEMI_R = Semi-Annual Latest, LTM = Last Twelve Months, LTM_R = Last Twelve Months Latest, LTMSG = Last Twelve Months Global, LTM_SEMI = Last Twelve Months Semi-Annual, YTD = Year-to-date.
      schema:
        type: string
        enum:
        - ANN
        - ANN_R
        - QTR
        - QTR_R
        - SEMI
        - SEMI_R
        - LTM
        - LTM_R
        - LTMSG
        - LTM_SEMI
        - YTD
        default: ANN
    currency:
      name: currency
      in: query
      required: false
      description: Currency code for currency values. For a list of currency ISO codes, visit Online Assistant Page 1470. Use "DOC" for reporting currency. Defaults to LOCAL.
      schema:
        type: string
        default: LOCAL
        examples:
        - USD
        - EUR
        - GBP
    fiscalPeriodEnd:
      name: fiscalPeriodEnd
      in: query
      required: false
      description: The fiscal period end expressed as YYYY-MM-DD. Calendar date that will fall back to the most recently completed period during resolution.
      schema:
        type: string
        format: date
        examples:
        - '2024-01-01'
    ratioMetrics:
      name: metrics
      in: query
      required: true
      explode: false
      description: Requested list of ratio metrics. Common ratios include FF_PE (price-to-earnings), FF_PBK (price-to-book), FF_ROE (return on equity), FF_DEBT_EQUITY, FF_CURR_RATIO, and others. Use the `/metrics` endpoint with category=RATIOS for a complete list.
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 1600
      examples:
        valuationRatios:
          summary: Common valuation ratios
          value:
          - FF_PE
          - FF_PBK
          - FF_PS
        profitabilityRatios:
          summary: Profitability ratios
          value:
          - FF_ROE
          - FF_ROA
          - FF_OPER_MARGIN
    ratioSubcategory:
      name: subcategory
      in: query
      required: false
      description: Filter ratios by subcategory. FINANCIAL for leverage and coverage ratios, GROWTH_RATE for revenue and earnings growth, LIQUIDITY for current and quick ratios, PROFITABILITY for margin and return metrics, SIZE for market cap and enterprise value, VALUATION for PE, PB, and dividend yield.
      schema:
        type: string
        enum:
        - FINANCIAL
        - GROWTH_RATE
        - LIQUIDITY
        - PROFITABILITY
        - SIZE
        - VALUATION
    ids:
      name: ids
      in: query
      required: true
      explode: false
      description: The requested list of security identifiers. Accepted ID types include Market Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids. Limit of 1,000 per non-batch request / 2,000 per batch request (GET) or 30,000 per batch request (POST).
      schema:
        type: array
        items:
          type: string
        minItems: 1
        maxItems: 2000
      examples:
        singleId:
          summary: One equity identifier
          value:
          - AAPL-US
        multipleIds:
          summary: Multiple equity 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