> ## 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 Statement Growth

> Year-over-year growth rates for income statement, cash flow, and balance sheet line items.

This endpoint returns period-over-period growth rates for revenue, profit, cash flow, and balance sheet line items, for every reporting period available.

By default, growth is computed **year-over-year against the same period label**, FY 2025 vs FY 2024, Q2 2025 vs Q2 2024, not sequentially. Sequential quarter-over-quarter comparison is noisy for seasonal businesses, so year-over-year is the safer default. Pass `compare=sequential` if you specifically want each period compared against the one immediately before it instead.

A growth rate comes back as `null` rather than a number in two situations: when there's no comparable prior period (the oldest period on file has nothing to compare against), and when the prior period's value was negative or zero. "Percent growth" from a loss or from zero isn't a meaningful figure, a company swinging from a ₦164B loss to a ₦105B profit isn't "growing 164%", so we don't pretend it is. The one exception is `dividends_paid_growth`, which is compared by magnitude rather than signed value, since `dividends_paid` is stored as a negative outflow by accounting convention, not because a company is in distress.

Use `periodType` (`annual` or `quarterly`) to restrict to one reporting cadence, omit it to get both together. `year` filters to a specific fiscal year, and `limit` caps the number of records returned. This endpoint requires a Pro plan or higher.

Depth depends on plan. Pro gets the last 3 years, annual only, `periodType` and `year` are ignored at this tier. Business and Enterprise get the full history, both annual and quarterly. Note that `compare=sequential` is only meaningfully different from the year-over-year default once quarterly data is available, comparing one annual period to the one right before it lands on the same result as comparing it to the same period last year, so this parameter mostly matters once you're on Business.

For example, to fetch the last 3 years of annual growth for Nestlé Nigeria:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.ngnmarket.com/v1/companies/NESTLE/financials/growth?periodType=annual&limit=3" \
    -H "Authorization: Bearer ngm_live_YOUR_KEY"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://api.ngnmarket.com/v1/companies/NESTLE/financials/growth');
  url.searchParams.set('periodType', 'annual');
  url.searchParams.set('limit', '3');

  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/NESTLE/financials/growth',
      params={'periodType': 'annual', 'limit': 3},
      headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
  )
  data = res.json()['data']
  ```
</CodeGroup>

To compare each quarter against the one right before it instead of the same quarter last year:

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

  ```javascript JavaScript theme={null}
  const url = new URL('https://api.ngnmarket.com/v1/companies/NESTLE/financials/growth');
  url.searchParams.set('periodType', 'quarterly');
  url.searchParams.set('compare', 'sequential');

  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/NESTLE/financials/growth',
      params={'periodType': 'quarterly', 'compare': 'sequential'},
      headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
  )
  data = res.json()['data']
  ```
</CodeGroup>


## OpenAPI

````yaml GET /companies/{symbol}/financials/growth
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/growth:
    get:
      tags:
        - Companies
      summary: Financial statement growth
      description: >
        Returns period-over-period growth rates for key income statement, cash
        flow, and balance sheet line items, for every reporting period
        available.


        By default, growth is computed **year-over-year against the same period
        label** (FY 2025 vs FY 2024, Q2 2025 vs Q2 2024), not sequentially,
        sequential comparison is noisy for seasonal businesses. Pass
        `compare=sequential` to compare each period against the one immediately
        before it instead.


        A growth rate is returned as `null` rather than a misleading number in
        two cases: when there's no comparable prior period (the oldest period on
        file), and when the prior period's value was negative or zero, since
        "percent growth" from a loss or from zero isn't a meaningful figure.
        `dividends_paid_growth` is the one exception, it's compared by magnitude
        rather than signed value, since dividends paid is stored as a negative
        outflow by convention, not because of financial distress.


        Use `periodType` (`annual` or `quarterly`) to restrict to one cadence,
        `year` to limit to a specific fiscal year, and `limit` to cap the number
        of records returned. This endpoint requires a Business plan or higher.


        **Plan required:** Pro
      operationId: getCompanyFinancialGrowth
      parameters:
        - name: symbol
          in: path
          description: NGX ticker symbol (e.g. `GTCO`). Case-insensitive.
          required: true
          schema:
            type: string
            example: NESTLE
        - name: periodType
          in: query
          description: >-
            Restrict to one reporting cadence. Omit to get both annual and
            quarterly periods together.
          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: compare
          in: query
          description: Comparison basis for the growth calculation.
          required: false
          schema:
            type: string
            enum:
              - yoy
              - sequential
            default: yoy
        - name: limit
          in: query
          description: Maximum number of periods to return (1–100).
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Growth metrics 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/GrowthPeriod'
                          count:
                            type: integer
                            example: 1
              examples:
                growth:
                  summary: FY 2025 growth for NESTLE (yoy)
                  value:
                    success: true
                    data:
                      data:
                        - period: For the year ended 31 December 2025
                          period_type: annual
                          year: 2025
                          quarter: FY
                          period_label: FY 2025
                          currency: NGN
                          revenue_growth: 0.2597
                          gross_profit_growth: 0.4228
                          operating_income_growth: 0.3426
                          net_income_growth: null
                          eps_growth: null
                          free_cash_flow_growth: 4.7671
                          dividends_paid_growth: -0.0603
                          total_assets_growth: -0.0146
                          shareholders_equity_growth: 1.1397
                      count: 1
                    meta:
                      plan: business
                      calls_used: 1209
                      calls_remaining: 498791
                      reset_at: '2026-05-15T23:57:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanRequired'
        '404':
          description: No financial growth data found for this symbol.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: No financial growth 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'
    GrowthPeriod:
      type: object
      description: >-
        Period metadata plus year-over-year (or sequential) growth rates. Null
        when there's no comparable prior period, or when the prior value was
        negative or zero.
      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, 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).
        revenue_growth:
          type: number
          nullable: true
        gross_profit_growth:
          type: number
          nullable: true
        operating_income_growth:
          type: number
          nullable: true
        net_income_growth:
          type: number
          nullable: true
        eps_growth:
          type: number
          nullable: true
        free_cash_flow_growth:
          type: number
          nullable: true
        dividends_paid_growth:
          type: number
          nullable: true
          description: >-
            Compared by magnitude, not signed value, since dividends_paid is
            stored as a negative outflow by convention.
        total_assets_growth:
          type: number
          nullable: true
        shareholders_equity_growth:
          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).

````