api-ninjas-com ETF API

openapi: 3.2.0
info:
  title: Ninjas ETF API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: ETF
  description: The ETF API provides detailed information about Exchange-Traded Funds including their holdings, expense ratios, assets under management, identifiers, and trailing total-return performance. It also exposes endpoints to list and search across all supported ETFs.
paths:
  /v1/etf:
    get:
      summary: Get ETF Information
      description: Returns holdings, expense ratio, assets under management and trailing total-return performance for one ETF. Look it up by `ticker`, or by `isin` to get the fund's most-traded listing. `listings` lists every exchange the same fund trades on. To find or enumerate ETFs use /etfsearch or /etflist.
      operationId: getETFInfo
      security:
      - ApiKeyAuth: []
      parameters:
      - name: ticker
        in: query
        required: false
        schema:
          type: string
        description: ETF ticker symbol (e.g., QQQ, SPY, VTI), including any exchange suffix (e.g. EUNL.DE). Either ticker or isin is required, not both.
      - name: isin
        in: query
        required: false
        schema:
          type: string
        description: 'International Securities Identification Number of the ETF (e.g., IE00B5BMR087). An ISIN identifies the fund, which may trade on several exchanges: the most-traded listing fills the response and every listing is returned in `listings`. Either ticker or isin is required, not both.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ETFResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - ETF
  /v1/etflist:
    get:
      summary: List Supported ETF Tickers
      description: Returns ETF ticker symbols supported by the ETF API, paginated up to 1000 per call. Increment the offset parameter by 1000 until fewer than 1000 results are returned to walk the entire list. Available to Business, Professional, or annual subscribers only.
      operationId: listETFs
      security:
      - ApiKeyAuth: []
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        description: Number of results to skip for pagination. Page size is 1000.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ETFListResponse'
        '400':
          description: Bad Request — Business, Professional, or annual subscription required
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - ETF
  /v1/etfsearch:
    get:
      summary: Search ETFs
      description: Search for ETFs by name, AUM, expense ratio, holdings, or country. Results are sorted by AUM descending and paginated 50 per page. At least one filter parameter is required. Available to Business, Professional, or annual subscribers only.
      operationId: searchETFs
      security:
      - ApiKeyAuth: []
      parameters:
      - name: name
        in: query
        required: false
        schema:
          type: string
        description: Fund name to search for (e.g. vanguard 500 matches Vanguard S&P 500 ETF). Case-insensitive. Each word must match the start of a word in the fund name, in any order, so ark matches ARK Innovation ETF but not Emerging Markets. Up to 12 words.
      - name: min_aum
        in: query
        required: false
        schema:
          type: number
        description: Minimum assets under management in USD.
      - name: max_aum
        in: query
        required: false
        schema:
          type: number
        description: Maximum assets under management in USD.
      - name: min_expense_ratio
        in: query
        required: false
        schema:
          type: number
        description: Minimum annual expense ratio as a percentage (e.g. 0.1 for 0.1%).
      - name: max_expense_ratio
        in: query
        required: false
        schema:
          type: number
        description: Maximum annual expense ratio as a percentage.
      - name: holdings
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated list of ticker symbols. Only ETFs that hold every listed ticker will be returned (AND match). Example: AAPL,MSFT.'
      - name: country
        in: query
        required: false
        schema:
          type: string
        description: Filter by ISO listing-country code -- the exchange the ETF trades on (e.g. US, GB, JP), not the fund's domicile.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
        description: Number of results to skip for pagination. Page size is 50.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                description: Array of up to 50 matching ETFs, sorted by USD AUM (descending).
                items:
                  type: object
                  properties:
                    symbol:
                      type: string
                      description: ETF ticker symbol.
                    name:
                      type: string
                      description: ETF name.
                    country:
                      type: string
                      description: ISO country code of the exchange the ETF is listed on. See domicile for the fund's legal home.
                    domicile:
                      type: string
                      description: ISO country code of the fund's legal domicile, which can differ from where it trades.
                    expense_ratio:
                      type: number
                      description: Annual expense ratio of the ETF as a percentage (e.g. 0.09 for 0.09%).
                    aum:
                      type: number
                      description: Assets under management of the ETF, in the fund's local trading currency (see aum_currency). Use aum_usd for a USD figure.
                    aum_currency:
                      type: string
                      description: ISO 4217 currency code that aum is denominated in (e.g. USD, JPY, EUR).
                    aum_usd:
                      type:
                      - number
                      - 'null'
                      description: Assets under management converted to USD. Results are sorted by this field.
                    num_holdings:
                      type: integer
                      description: Number of holdings in the ETF.
        '400':
          description: Bad Request — missing filters or subscription tier too low
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      tags:
      - ETF
components:
  schemas:
    FundPerformance:
      type: object
      description: Trailing returns for this share class, based on monthly total returns with distributions reinvested. Values are percentages.
      properties:
        as_of:
          type: string
          format: date
          description: Last month-end the figures cover.
        months_available:
          type: integer
          description: Number of monthly returns on file.
        return_1m:
          type:
          - number
          - 'null'
          description: Total return over the most recent month, in percent.
        return_3m:
          type:
          - number
          - 'null'
          description: Cumulative total return over the trailing 3 months, in percent.
        return_6m:
          type:
          - number
          - 'null'
          description: Cumulative total return over the trailing 6 months, in percent.
        return_ytd:
          type:
          - number
          - 'null'
          description: Cumulative total return from January of the as-of year, in percent.
        return_1y:
          type:
          - number
          - 'null'
          description: Cumulative total return over the trailing 12 months, in percent.
        return_3y:
          type:
          - number
          - 'null'
          description: Cumulative total return over the trailing 36 months, in percent.
        return_5y:
          type:
          - number
          - 'null'
          description: Cumulative total return over the trailing 60 months, in percent.
        annualized_3y:
          type:
          - number
          - 'null'
          description: Trailing 3-year return annualized (geometric), in percent.
        annualized_5y:
          type:
          - number
          - 'null'
          description: Trailing 5-year return annualized (geometric), in percent.
        since:
          type: string
          format: date
          description: First month of history.
        return_since:
          type:
          - number
          - 'null'
          description: Cumulative total return since `since`, in percent.
        annualized_since:
          type:
          - number
          - 'null'
          description: Return since `since`, annualized, in percent.
        best_month:
          $ref: '#/components/schemas/FundMonthlyReturn'
        worst_month:
          $ref: '#/components/schemas/FundMonthlyReturn'
        volatility_3y:
          type:
          - number
          - 'null'
          description: Annualized standard deviation of monthly returns over the trailing 36 months, in percent.
        monthly_returns:
          type: array
          description: Every month on file, oldest first.
          items:
            $ref: '#/components/schemas/FundMonthlyReturn'
    FundMonthlyReturn:
      type: object
      properties:
        month:
          type: string
          description: Return month as YYYY-MM.
        total_return:
          type: number
          description: Total return for that month, in percent.
    ETFResponse:
      type: object
      properties:
        etf_ticker:
          type: string
          description: ETF ticker symbol.
        etf_name:
          type: string
          description: ETF name.
        isin:
          type: string
          description: International Securities Identification Number (ISIN) of the ETF.
        cusip:
          type: string
          description: Nine-character Committee on Uniform Security Identification Procedures (CUSIP) identifier for the ETF.
        country:
          type: string
          description: ISO country code of the exchange the ETF is listed on (e.g. a Tokyo-listed ETF is JP). See domicile for the fund's legal home.
        domicile:
          type: string
          description: ISO country code of the fund's legal domicile, which can differ from where it trades (e.g. an Ireland-domiciled UCITS listed in London is country GB, domicile IE).
        price:
          type: number
          description: Current price of this listing, in its trading currency (see the matching entry in listings). Premium members receive the live price; free users receive the closing price of the most recent completed trading session.
        expense_ratio:
          type: number
          description: Annual expense ratio of the ETF as a percentage.
        aum:
          type: number
          description: Assets under management of the ETF, in the fund's local trading currency (see aum_currency). Use aum_usd for a USD figure.
        aum_currency:
          type: string
          description: ISO 4217 currency code that aum is denominated in (e.g. USD, JPY, EUR).
        aum_usd:
          type:
          - number
          - 'null'
          description: Assets under management converted to USD.
        num_holdings:
          type: integer
          description: Number of holdings in the ETF.
        holdings:
          type: array
          items:
            type: object
            properties:
              ticker:
                type: string
                description: Ticker of the holding. Empty for positions that have no ticker, such as cash, futures and money-market sweeps.
              name:
                type:
                - string
                - 'null'
                description: Name of the security or position. For holdings without a ticker it says what the position is (for example a futures contract or cash).
              isin:
                type:
                - string
                - 'null'
                description: ISIN of the security, or null when it has none (cash, futures and other non-securities).
              cusip:
                type:
                - string
                - 'null'
                description: CUSIP (or CINS for non-US issuers) of the security, or null when it has none.
              num_shares:
                type: integer
              weight:
                type: number
              value:
                type: number
              last_updated:
                type: integer
          description: Array of all holdings in the ETF, each with ticker, num_shares, weight (decimal fraction), value and last_updated (Unix timestamp).
        performance:
          allOf:
          - $ref: '#/components/schemas/FundPerformance'
          description: Trailing returns for this ETF. Business tier and above.
        listings:
          type: array
          items:
            $ref: '#/components/schemas/ETFListing'
          description: Every exchange this fund trades on, most traded first. Holdings, expense ratio and aum_usd are the same whichever listing you look up. Listings with no trades in the last 14 days are left out.
    ETFListing:
      type: object
      properties:
        ticker:
          type: string
          description: Ticker of this listing, with exchange suffix (e.g. SXR8.DE).
        exchange:
          type: string
          description: Exchange code (e.g. LSE, XETRA, NASDAQ).
        country:
          type:
          - string
          - 'null'
          description: ISO country code of the exchange.
        currency:
          type:
          - string
          - 'null'
          description: 'Trading currency: an ISO 4217 code, or GBX (UK pence) or ZAC (South African cents) for listings quoted in those units.'
        price:
          type:
          - number
          - 'null'
          description: Latest price in currency. Premium only.
        volume:
          type:
          - integer
          - 'null'
          description: Shares traded in the latest session. Premium only.
        avg_volume:
          type:
          - integer
          - 'null'
          description: Average shares traded per day. Premium only.
    ETFListResponse:
      type: array
      items:
        type: string
      description: Array of every supported ETF ticker symbol.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api