The short version
Non-US listings
Non-US listings are addressed the way Google Finance writes them: an exchange prefix, a colon, then the local ticker.%3A) if your HTTP client needs it. Both forms work.
The prefix names the listing venue when the company’s home country has no
prefix of its own: a Cayman-registered company listed in Hong Kong is
HKG:2020 (ANTA), and a Jersey company on the London Stock Exchange is
LON:GLEN (Glencore). When the home country has one, the identifier carries
it: China Shenhua’s Hong Kong H-shares are SHA:1088, and HKG:1088 reaches
the same listing. The prefixes in the second table below follow the venue:
Turkcell on Borsa Istanbul is IST:TCELL, while an Israeli company listed on
Nasdaq keeps its bare ticker as its instrument_id (TLV: plus that ticker
still reaches it). Every instrument and search response carries
instrument_id, the exact string to send, so you never have to assemble one
from symbol and country_code.
These name the listing on that venue:
Other spellings that resolve
You do not have to learn the table. The way Google Finance writes a venue (EPA:AI, EBR:UCB, ETR:SAP, BIT:ENI, ELI:EDP), the venue’s own name or
code (HKEX:0669, LSE:AZN, XETRA:SAP, NZX:FPH, BME:AMS, TWSE:2330,
KOSPI:005930, BIST:THYAO, TASE:TEVA, MOEX:SBER), and a US venue written as a prefix (NASDAQ:AAPL,
NYSE:JPM) all resolve to the same listing. TSE: is read as Tokyo when the
ticker is numeric (TSE:7203) and as Toronto when it is not (TSE:SHOP).
A Hong Kong stock code answers to any zero-padding: HKG:992, HKG:0992 and
HKG:00992 all reach Lenovo.
POST /screen takes the same identifiers as /instruments, prefixed or bare,
up to 50 per call, and echoes each one back in upper case. Dotted share classes
(BRK.B) resolve everywhere.
Cross-listings and share classes
A company is analysed once, against its canonical listing. Ask for any listing of it (an ADR, a foreign line, a second share class) and you get that company’s determination, echoed back under the symbol you asked for. SoNVO and
CPH:NOVO-B return the same screens, and BRK-B returns Berkshire.
Funds
Funds live on/etfs/{symbol}, not
/instruments. Around 180 fund tickers also exist as equity rows for
bookkeeping reasons, so /instruments/SPY/compliance answers pending
forever; when it does, the response carries meta.etf naming the endpoint that
has the real answer. POST /screen does the
same through meta.etfs.
The exception is a fund we screen under AAOIFI as a trust rather than by
holdings (GLD, IAU, SLV, IBIT, USO). Those carry a real determination
on /instruments, and /etfs has little to say about them.
A fund’s alternate listing line, a same-ISIN ticker on another currency or
exchange, resolves to the fund itself.
When an identifier does not resolve
404 not_found means we have no such instrument. The message names the likely
fix when there is one: the prefixed form for a vendor-suffixed ticker, or the
fund endpoint for a fund ticker. On /screen, unresolvable tickers come back
in meta.not_found rather than as fabricated rows, and the fund ones are named
in meta.etfs.
Use GET /search when you have a name and
need the identifier: every stock hit carries instrument_id, the exact string
to send to /instruments, and every hit carries a type telling you whether
to route it to /instruments or /etfs.
GET /instruments/{symbol}/health can 404 for a listing that resolves
everywhere else. Financial health is computed from SEC filings, so a company
that does not file with the SEC has no health analysis yet; the message says
so, and the compliance determination is unaffected.