> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngnmarket.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Financial Ratios

> Retrieve just the computed financial ratios for an NGX-listed company.

This endpoint returns just the computed financial ratios for every reporting period available, ordered from most recent to oldest. It's the same data you'd find under `ratios` in the combined financials endpoint, returned on its own so you're not paying for the income statement, balance sheet, and cash flow sections when you only need margins, returns, and per-share figures.

Some ratios (gross margin, operating margin, net profit margin, return on equity, return on assets) are stored directly from the filed statements. The rest (current ratio, debt to equity, interest coverage, free cash flow margin, book value per share, free cash flow per share, revenue per share) are computed at request time from the underlying statements. A ratio comes back as `null` when one of its inputs isn't available for that period.

Use `periodType` (`annual` or `quarterly`) to filter by statement type, `year` to limit results to a specific fiscal year, and `limit` to control the maximum number of records returned. This endpoint requires a Starter plan or higher.

Depth depends on plan. Starter gets the most recent annual period only, essentially the current year. Pro extends that to the last 3 years, annual only. On both of these tiers, `periodType` and `year` are ignored since the response is already capped to a fixed, recent window. Business and Enterprise get the full history, both annual and quarterly, with `periodType` and `year` fully respected.

For example, to fetch GTCO's quarterly ratios for 2025:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.ngnmarket.com/v1/companies/GTCO/financials/ratios?periodType=quarterly&year=2025" \
    -H "Authorization: Bearer ngm_live_YOUR_KEY"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://api.ngnmarket.com/v1/companies/GTCO/financials/ratios');
  url.searchParams.set('periodType', 'quarterly');
  url.searchParams.set('year', '2025');

  const res = await fetch(url, {
    headers: { Authorization: 'Bearer ngm_live_YOUR_KEY' },
  });
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      'https://api.ngnmarket.com/v1/companies/GTCO/financials/ratios',
      params={'periodType': 'quarterly', 'year': 2025},
      headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
  )
  data = res.json()['data']
  ```
</CodeGroup>


## OpenAPI

````yaml GET /companies/{symbol}/financials/ratios
openapi: 3.1.0
info:
  title: NGN Market API
  version: '1.0'
  description: >
    The NGN Market API provides programmatic access to Nigerian Exchange Group
    (NGX) market data, including equities, forex rates, company profiles,
    indices, bonds, and financial news.


    ## Base URL


    All endpoints are served from:


    ```

    https://api.ngnmarket.com/v1

    ```


    ## Authentication


    Every request requires a Bearer token in the `Authorization` header:


    ```

    Authorization: Bearer ngm_live_YOUR_KEY

    ```


    Generate and manage your API keys from the [developer
    dashboard](https://ngnmarket.com/developer).


    ## Plans & Quotas


    | Plan | Monthly Calls | Requests/min | Price |

    | :--- | ---: | ---: | :--- |

    | Free | 3,000 | 30 | Free |

    | Hobby | 10,000 | 60 | ₦15,000/mo |

    | Starter | 100,000 | 120 | ₦50,000/mo |

    | Pro | 250,000 | 120 | ₦100,000/mo |

    | Business | 2,000,000 | 300 | ₦300,000/mo |

    | Enterprise | Unlimited | Unlimited | Custom |


    Every response includes a `meta` object showing your current usage and
    remaining quota. Exceeding the per-minute rate limit returns `429
    RATE_LIMITED`. Exceeding the monthly quota returns `429 QUOTA_EXCEEDED`.


    ## Response Envelope


    All responses use a consistent JSON envelope:


    ```json

    {
      "success": true,
      "data": { ... },
      "meta": {
        "plan": "starter",
        "calls_used": 4821,
        "calls_remaining": 95179,
        "reset_at": "2026-05-15T23:57:00.000Z"
      }
    }

    ```
  contact:
    name: NGN Market Support
    email: support@ngnmarket.com
    url: https://ngnmarket.com
  license:
    name: Proprietary
servers:
  - url: https://api.ngnmarket.com/v1
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Market
    description: >-
      Daily market snapshots, top trades, movers, market breadth, sectors, and
      YTD performers.
  - name: Companies
    description: >-
      Browse, search, and retrieve profiles, price charts, and financial
      statements for NGX-listed companies.
  - name: Forex
    description: Current and historical NGN exchange rates against major currencies.
  - name: Indices
    description: >-
      All NGX market indices, including list, detail with constituents, and
      historical chart data.
  - name: ETFs
    description: >-
      NGX-listed Exchange Traded Funds and ETPs — list, full fund detail, and
      historical daily price data.
  - name: Bonds
    description: >-
      NGX-listed bond instruments with issuer details, coupon rates, and
      maturity dates.
  - name: Disclosures
    description: >-
      Official corporate filings from NGX-listed companies (financial
      statements, AGM notices, board meetings, director dealings, earnings
      forecasts). Sourced from NGX Group and updated twice daily.
  - name: Blog
    description: >-
      Published NGN Market blog posts. List, search, and filter by category or
      company.
  - name: Dividends
    description: >-
      Market-wide NGX dividend calendar. Browse upcoming and recently paid
      dividends across all listed companies with optional search and pagination.
  - name: Account
    description: >-
      Quota status, 30-day request analytics, and paginated request logs for the
      authenticated user.
paths:
  /companies/{symbol}/financials/ratios:
    get:
      tags:
        - Companies
      summary: Financial ratios
      description: >
        Returns just the computed financial ratios for every reporting period
        available, ordered from most recent to oldest. This is the same data
        returned under `ratios` in the combined financials endpoint, on its own
        so you don't have to pull the income statement, balance sheet, and cash
        flow along with it.


        Some ratios (gross margin, operating margin, net profit margin, return
        on equity, return on assets) are stored directly. The rest (current
        ratio, debt to equity, interest coverage, free cash flow margin, book
        value per share, free cash flow per share, revenue per share) are
        computed at request time from the underlying statements. A ratio is
        `null` when one of its inputs is unavailable for that period.


        **Plan required:** Starter
      operationId: getCompanyFinancialRatios
      parameters:
        - name: symbol
          in: path
          description: NGX ticker symbol (e.g. `GTCO`). Case-insensitive.
          required: true
          schema:
            type: string
            example: DANGCEM
        - name: periodType
          in: query
          description: Filter by reporting period type.
          required: false
          schema:
            type: string
            enum:
              - annual
              - quarterly
        - name: year
          in: query
          description: Filter by calendar year (e.g. `2025`).
          required: false
          schema:
            type: integer
            example: 2025
        - name: limit
          in: query
          description: Maximum number of periods to return (1–100).
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Financial ratios retrieved successfully.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          data:
                            type: array
                            items:
                              $ref: '#/components/schemas/RatiosPeriod'
                          count:
                            type: integer
                            description: Total number of reporting periods returned.
                            example: 1
              examples:
                ratios:
                  summary: Full-year ratios for DANGCEM
                  value:
                    success: true
                    data:
                      data:
                        - period: '2025-12-31'
                          period_type: annual
                          year: 2025
                          quarter: FY
                          period_label: FY 2025
                          currency: NGN
                          gross_margin: 52.16
                          operating_margin: 38.91
                          net_profit_margin: 26.91
                          return_on_equity: 44.37
                          return_on_assets: 23.77
                          current_ratio: 1.62
                          debt_to_equity: 0.56
                          interest_coverage: 10.72
                          free_cash_flow_margin: 21.36
                          bvps: 83.33
                          fcfps: 29.34
                          revenue_per_share: 137.38
                      count: 1
                    meta:
                      plan: business
                      calls_used: 1204
                      calls_remaining: 1998796
                      reset_at: '2026-05-15T23:57:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanRequired'
        '404':
          description: No ratio data found for this symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: No ratio data found for 'UNKNOWN'.
        '429':
          $ref: '#/components/responses/QuotaExceeded'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          const: true
        meta:
          $ref: '#/components/schemas/Meta'
    RatiosPeriod:
      type: object
      description: >-
        Period metadata plus the computed ratio fields, flattened into one
        object. Values are null when inputs are unavailable.
      properties:
        period:
          type: string
          description: Raw period string as filed (e.g. 2025-12-31).
        period_type:
          type: string
          enum:
            - annual
            - quarterly
        year:
          type: integer
        quarter:
          type: string
          description: Q1, Q2, Q3, Q4, H1, 9M, or FY.
        period_label:
          type: string
          description: Human-readable label (e.g. FY 2025, Q3 2025).
        currency:
          type: string
          description: ISO 4217 currency code (typically NGN).
        gross_margin:
          type: number
          nullable: true
        operating_margin:
          type: number
          nullable: true
        net_profit_margin:
          type: number
          nullable: true
        return_on_equity:
          type: number
          nullable: true
        return_on_assets:
          type: number
          nullable: true
        current_ratio:
          type: number
          nullable: true
        debt_to_equity:
          type: number
          nullable: true
        interest_coverage:
          type: number
          nullable: true
        free_cash_flow_margin:
          type: number
          nullable: true
        bvps:
          type: number
          nullable: true
        fcfps:
          type: number
          nullable: true
        revenue_per_share:
          type: number
          nullable: true
    ErrorEnvelope:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error identifier.
              example: NOT_FOUND
            message:
              type: string
              description: Human-readable error description.
              example: Resource not found.
            required_plan:
              type: string
              description: _(PLAN_REQUIRED only)_ Minimum plan needed.
            current_plan:
              type: string
              description: _(PLAN_REQUIRED only)_ Your current plan.
    Meta:
      type: object
      description: Quota and plan metadata included on every authenticated response.
      properties:
        plan:
          type: string
          description: Current plan name.
          enum:
            - free
            - hobby
            - starter
            - pro
            - business
            - enterprise
          example: starter
        calls_used:
          type: integer
          description: Total calls made this calendar month across all your keys.
          example: 4821
        calls_remaining:
          type: integer
          description: Calls remaining before your quota is exhausted.
          example: 95179
        reset_at:
          type: string
          format: date-time
          description: >-
            ISO 8601 UTC timestamp of your next quota reset (your account's
            billing renewal date, not the calendar month start).
          example: '2026-06-15T23:57:00.000Z'
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            missingKey:
              summary: Missing Authorization header
              value:
                success: false
                error:
                  code: MISSING_API_KEY
                  message: 'Provide your API key via: Authorization: Bearer <key>'
            invalidKey:
              summary: Invalid or revoked key
              value:
                success: false
                error:
                  code: INVALID_API_KEY
                  message: API key not found or revoked.
    PlanRequired:
      description: Endpoint requires a higher plan.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PLAN_REQUIRED
              message: This endpoint requires a starter plan or higher.
              required_plan: starter
              current_plan: free
    QuotaExceeded:
      description: Monthly call limit reached.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ErrorEnvelope'
              - type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/Meta'
          example:
            success: false
            error:
              code: QUOTA_EXCEEDED
              message: >-
                Monthly call limit of 100,000 reached. Resets on
                2026-05-01T00:00:00.000Z.
            meta:
              plan: starter
              calls_used: 100000
              calls_remaining: 0
              reset_at: '2026-05-15T23:57:00.000Z'
    ServerError:
      description: Unexpected server-side failure. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: SERVER_ERROR
              message: Something went wrong on our end. Please try again.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: ngm_live_*
      description: >
        Pass your API key as a Bearer token: `Authorization: Bearer
        ngm_live_YOUR_KEY`.

        Generate keys at
        [ngnmarket.com/dashboard/developer](https://ngnmarket.com/developer).

````