> ## 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.

# List Companies

> Retrieve a paginated, filterable list of all NGX-listed companies.

The list endpoint returns all companies currently listed on the Nigerian Exchange Group (NGX). You can paginate through results, narrow them to a specific sector, or search by company name or ticker symbol.

Each company includes its current price, market capitalisation, trading volume, and percentage changes across multiple time frames, plus a `logo_url` you can drop straight into an `<img>` tag. Sort and filter options let you rank companies by any of these fields.

<Note>
  `logo_url` is a 200×200 PNG served from a CDN, ready to use with no setup. If you need WebP, favicon-sized ICOs, or logos bundled into your own build, see the [company logos guide](/guides/company-logos).
</Note>

For example, to fetch the 25 largest Financial Services companies sorted by market cap:

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.ngnmarket.com/v1/companies?sector=Financial%20Services&limit=25&sort=market_cap&order=desc" \
    -H "Authorization: Bearer ngm_live_YOUR_KEY"
  ```

  ```javascript JavaScript theme={null}
  const url = new URL('https://api.ngnmarket.com/v1/companies');
  url.searchParams.set('sector', 'Financial Services');
  url.searchParams.set('limit', '25');
  url.searchParams.set('sort', 'market_cap');
  url.searchParams.set('order', 'desc');

  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',
      params={
          'sector': 'Financial Services',
          'limit': 25,
          'sort': 'market_cap',
          'order': 'desc',
      },
      headers={'Authorization': 'Bearer ngm_live_YOUR_KEY'},
  )
  data = res.json()['data']
  ```
</CodeGroup>

Use `search` instead of `sector` for partial-match lookups by ticker or name (`search=DAN` matches `DANGCEM`).


## OpenAPI

````yaml GET /companies
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 |

    | Growth | 500,000 | 200 | ₦200,000/mo |

    | Business | 2,000,000 | 300 | ₦700,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-01T00:00: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:
    get:
      tags:
        - Companies
      summary: Browse NGX-listed companies
      description: >
        Returns a paginated, filterable list of all NGX-listed companies with
        current price data. Filter by sector, search by name or ticker, sort by
        market cap, price, or other fields, and apply market-cap range filters.


        Price fields (`current_price`, `price_change`, `volume`, etc.) reflect
        the most recent intraday data. Prices are refreshed **every 20 minutes
        during NGX trading hours (Monday–Friday, 09:00–16:00 WAT)**. Outside
        trading hours, values reflect the most recent session close.


        **Plan required:** Free
      operationId: listCompanies
      parameters:
        - name: page
          in: query
          description: Page number to return. Starts at `1`.
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Number of results per page. Maximum `200`.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: sector
          in: query
          description: >-
            Filter to a specific NGX sector. Must match exactly (e.g.
            `Industrial Goods`, `Financial Services`).
          required: false
          schema:
            type: string
            example: Financial Services
        - name: search
          in: query
          description: >-
            Search by company name or ticker symbol. Case-insensitive, partial
            match. `DAN` matches `DANGCEM`.
          required: false
          schema:
            type: string
            example: DAN
        - name: sort
          in: query
          description: Field to sort results by.
          required: false
          schema:
            type: string
            enum:
              - symbol
              - company_name
              - sector
              - current_price
              - market_cap
              - volume
              - price_change_percent
              - shares_outstanding
              - change_7d_percent
              - change_52w_percent
            default: market_cap
        - name: order
          in: query
          description: Sort direction.
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: minMarketCap
          in: query
          description: Minimum market cap filter (in NGN).
          required: false
          schema:
            type: number
        - name: maxMarketCap
          in: query
          description: Maximum market cap filter (in NGN).
          required: false
          schema:
            type: number
      responses:
        '200':
          description: Companies 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/CompanyListItem'
                          pagination:
                            $ref: '#/components/schemas/Pagination'
              examples:
                companiesList:
                  summary: Paginated company list
                  value:
                    success: true
                    data:
                      data:
                        - id: 12
                          symbol: DANGCEM
                          name: Dangote Cement Plc
                          logo_url: >-
                            https://cdn.jsdelivr.net/gh/ngnmarket/ngx-logos/dist/png/DANGCEM.png
                          sector: Industrial Goods
                          sub_sector: Building Materials
                          market_classification: Main Board
                          shares_outstanding: 17040507405
                          website: https://dangotecement.com
                          price: 302.5
                          prev_close: 300
                          day_high: 305
                          day_low: 299.5
                          volume: 1284729
                          market_cap: 8291047302
                          price_change: 2.5
                          price_change_percent: 0.83
                          change_7d_percent: 1.2
                          change_52w_percent: 14.5
                          high52wk: 320
                          low52wk: 258
                          last_updated: '2026-04-21T14:30:00.000Z'
                      pagination:
                        page: 1
                        limit: 5
                        total: 150
                        total_pages: 30
                    meta:
                      plan: free
                      calls_used: 42
                      calls_remaining: 9958
                      reset_at: '2026-05-01T00:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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'
    CompanyListItem:
      type: object
      properties:
        id:
          type: integer
        symbol:
          type: string
          example: DANGCEM
        name:
          type: string
          example: Dangote Cement Plc
        logo_url:
          type: string
          description: URL of the company's logo image.
          example: https://cdn.jsdelivr.net/gh/ngnmarket/ngx-logos/dist/png/DANGCEM.png
        sector:
          type: string
          example: Industrial Goods
        sub_sector:
          type: string
          example: Building Materials
        market_classification:
          type: string
          example: Main Board
        shares_outstanding:
          type: number
        website:
          type: string
        price:
          type: number
          description: Current trading price (NGN).
        prev_close:
          type: number
        day_high:
          type: number
        day_low:
          type: number
        volume:
          type: number
        market_cap:
          type: number
        price_change:
          type: number
        price_change_percent:
          type: number
        change7dPercent:
          type: number
        change52wPercent:
          type: number
        high52wk:
          type: number
        low52wk:
          type: number
        last_updated:
          type: string
          format: date-time
          description: >-
            ISO 8601 timestamp of the last price update. Prices refresh every 20
            minutes during NGX trading hours (Monday–Friday, 09:00–16:00 WAT).
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 50
        total:
          type: integer
          example: 150
        total_pages:
          type: integer
          example: 3
    Meta:
      type: object
      description: Quota and plan metadata included on every authenticated response.
      properties:
        plan:
          type: string
          description: Current plan name.
          enum:
            - free
            - starter
            - growth
            - 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 (1st of next month).
          example: '2026-05-01T00:00:00.000Z'
    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.
  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.
    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-01T00:00: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).

````