Get securities and listings
Available securities and listing venues for a company, fund or share class, with their identifiers.
How it works
-
One entry per security. Each entry has an ISIN. A share class can have identifiers and an empty
venueslist when no exchange listing is established. -
is_primarymarks a supported primary listing. It is null when the primary is unknown. A venue can reflect a documented admission. Its currency is null when the trading currency of that line is unknown. - Primary lines appear first. Within each priority, venues are grouped by operating market. Lines with a ticker precede tickerless admissions on the same market. Each segment retains its own MIC.
-
Currencies are ISO 4217 codes, never minor units. A London line quoted in pence has
currencyGBP, Johannesburg cents are ZAR and Tel Aviv agorot ILS. - Ticker formats depend on the source. The reported ticker can use a different format from the symbol shown by the exchange.
-
Every venue can be looked up again. Send its
tickerandmic(oroperating_mic) back asticker:mic, such asAPC:XBERfor Apple in Berlin, to get the same security. -
If we can't tell which company you mean, you get a 404 saying so. Add the exchange to the ticker, or use an ISIN:
TSCO:LNrather thanTSCO.
Request
GET /api/v1/listings with your API key. AI assistants call it as the get_listings tool, with the same parameters.
Parameters
qstringrequired
Ticker with its exchange code or MIC (AAPL:US, AAPL:XNAS, TSCO:XLON), ISIN, CUSIP, SEDOL, WKN, FIGI, LEI, CIK or company registration number. Any ticker and mic a listing returns work as ticker:mic.
More parameters
include_sourcesboolean
Include available source documents and supporting evidence. Omit for data only.
Default: false
Response
JSON with these fields. A field the source doesn't report is null or left out. When nothing matches, message says why and what to ask instead. Empty answers are free.
queryThe identifier asked for
identifier_typeType of the submitted identifier, null when ambiguous
listingsarray of objectsrequired
Show child attributes
isinISIN of the security
cusipReported CUSIP for this ISIN; null when conflicting
sedolReported SEDOL for this ISIN; null when conflicting
wknReported WKN for this ISIN; null when conflicting
share_class_figiReported share-class FIGI for this ISIN; null when conflicting
venuesarray of objectsrequired
Show child attributes
tickerReported ticker for this trading line, which may use the source's symbol format
exchangeExchange name
micMost specific ISO 10383 MIC of the trading line: a segment MIC (XNGS) or, off-segment, the operating MIC
operating_micISO 10383 MIC of the exchange that runs the segment (XNAS for XNGS); equal to mic on the operating market itself
countryISO 3166-1 alpha-2 country code of the exchange
currencyISO 4217 currency of this listing, never a minor unit: a London line quoted in pence is GBP. Null when unavailable or conflicting
figiFIGI of this trading line (venue level)
composite_figiCountry-level composite FIGI of this listing
listed_onReported listing date at this exchange, not necessarily the company's IPO date
is_primaryWhether it's the primary listing; null when the primary is unknown
matchIdentifier lookup outcome. A found match can still have an empty page.
messageOnly when there are no listings: why, and what to ask instead
Errors
| Status | Meaning |
|---|---|
| 400 | Missing, unknown or invalid parameter, or an identifier that can't be looked up |
| 401 | Missing, unknown or revoked API key |
| 402 | No active plan or trial, or the included request allowance is used |
| 403 | API access of the account is suspended |
| 404 | The identifier matches nothing or is ambiguous. The match field identifies the outcome |
| 429 | Over the plan's rate limit; Retry-After says when to retry |
| 500 | Internal error; the same request is unlikely to succeed on retry |
| 503 | The data couldn't be loaded right now; Retry-After says when to retry, when known |
Errors are JSON with an error message saying what to fix. Errors are free. See Errors and limits.