Symbols

yfin accepts Yahoo Finance-style symbols across the REST API and SDKs. A symbol usually identifies one tradable instrument or index, such as AAPL, MSFT, SPY, ^GSPC, BTC-USD, or EURUSD=X.

Symbol Inputs

Use the symbol exactly as it appears in Yahoo Finance search results when you want the broadest compatibility.

curl "https://api.yfin.dev/v1/quote?symbols=AAPL,MSFT,BTC-USD,^GSPC" \
  -H "X-Yfin-Contact: [email protected]"

import yfin as yf

tickers = yf.download(["AAPL", "MSFT", "BTC-USD"], period="5d")

Asset Types

Common symbol classes include:

Type	Examples	Notes
US equities	AAPL, MSFT, NVDA	Most quote, history, options, and fundamentals routes support these well.
ETFs and funds	SPY, QQQ, VTI	Fundamentals and holdings data depends on the fund.
Indexes	^GSPC, ^IXIC, ^DJI	Options and fundamentals are not available for every index.
Crypto pairs	BTC-USD, ETH-USD	Market-hours behavior differs from exchange-traded securities.
FX pairs	EURUSD=X, JPY=X	Quote and chart data are usually the most relevant endpoints.
International listings	7203.T, SHOP.TO, VOD.L	Use the exchange suffix returned by search.

Search Before Quote

When a user enters a company name or partial ticker, search first and then call quote or history with the selected symbol.

curl "https://api.yfin.dev/v1/search?q=apple" \
  -H "X-Yfin-Contact: [email protected]"

import { Client } from "@yfin/sdk";

const client = new Client({ contact: "[email protected]" });
const matches = await client.search("apple");

Use /v1/autocomplete for search boxes and /v1/lookup when you need a wider lookup response for a user-entered query.

Region And Language

Many endpoints accept region and lang. Use these when the user is searching outside the US or when display names should match a locale.

curl "https://api.yfin.dev/v1/search?q=toyota&region=JP&lang=en-US"

Practical Rules

• Store the returned symbol, not the display name.
• Do not infer the asset type from formatting alone. Use quote type fields when you need to branch behavior.
• Treat symbols as case-sensitive for display and case-insensitive only where your own UI explicitly normalizes input.
• For international listings, keep the exchange suffix. SHOP and SHOP.TO are different instruments.
• For user-facing apps, search or autocomplete before making assumptions about the intended instrument.