Find the exact listing to pass to every other route. A US listing is its bare ticker (`AAPL`, `BRK-B`); a listing on another exchange is `MIC:TICKER`, its ISO 10383 market identifier code and ticker (`XETR:SIE`, `XLIS:NOS`). Every `ticker` these endpoints return is accepted back by the [price](/docs/api/endpoints/prices), company and dataset routes. `exchange` names the market identifier code of a listing outside the US and is absent for a US listing.

## Listings

`GET /v1/listings`

Pass one of:

- `query`: a company name or ticker, ranked as the site search ranks it: exact tickers first, then names, then larger companies. A `MIC:` prefix (`XETR:siemens`) keeps one exchange.
- `isin`: every listing of that security, each in its own currency. A US or Canadian ISIN also matches a US listing by the CUSIP it embeds, so `US0378331005` finds `AAPL`. A US listing states its `cusip`; its `isin` is `null` unless one is on record.
- `exchange` on its own: every listing of that exchange, in ticker order.
- `market` on its own: every listing of that country, in exchange then ticker order; `US` lists the SEC directory.

`securityType` comes from the security's authoritative registration and reads `Unknown` where none states it; a fund listed on another exchange reads `ExchangeTradedFund`, and an exchange-traded commodity or note reads `ExchangeTradedNote`. `exchangeTradedProduct` is `true` for a US ETF or ETN in the market-data reference directory and for those funds, commodities and notes; [ETFs](/docs/api/endpoints/etfs) covers them. `primary` marks the company's main listing.

**Parameters:** `query` or `isin` (not both); optional `exchange` (a market identifier code from [Markets](#markets), to narrow a search or to list one exchange); `market` (an ISO country code, used on its own); `limit` (default 20, max 500); `offset`. An invalid ISIN, an unknown exchange or country, or a disallowed combination returns `400 invalid_parameter`.

```bash
curl "https://api.equibles.com/v1/listings?exchange=XLIS&limit=2" \
  -H "Authorization: Bearer eq_your_api_key"
```

```python
import requests
r = requests.get(
    "https://api.equibles.com/v1/listings",
    params={"exchange": "XLIS", "limit": 2},
    headers={"Authorization": "Bearer eq_your_api_key"},
)
print(r.json())
```

```javascript
const res = await fetch("https://api.equibles.com/v1/listings?exchange=XLIS&limit=2", {
  headers: { Authorization: "Bearer eq_your_api_key" },
});
console.log(await res.json());
```

```json
{
  "data": [
    { "ticker": "XLIS:ALTR", "exchange": "XLIS", "market": "PT", "currency": "EUR", "isin": "PTALT0AE0002",
      "companyName": "ALTRI, S.G.P.S., S.A.", "securityType": "Unknown", "primary": true, "exchangeTradedProduct": false },
    { "ticker": "XLIS:BCP", "exchange": "XLIS", "market": "PT", "currency": "EUR", "isin": "PTBCP0AM0015",
      "companyName": "BANCO COMERCIAL PORTUGUÊS S.A.", "securityType": "Unknown", "primary": true, "exchangeTradedProduct": false }
  ],
  "meta": { "limit": 2, "offset": 0, "count": 2, "hasMore": true }
}
```

An ISIN, `GET /v1/listings?isin=US0378331005`:

```json
{
  "data": [
    { "ticker": "AAPL", "market": "US", "currency": "USD", "isin": null, "cusip": "037833100",
      "companyName": "Apple Inc.", "securityType": "Unknown", "primary": true, "exchangeTradedProduct": false }
  ],
  "meta": { "limit": 20, "offset": 0, "count": 1, "hasMore": false }
}
```

## Markets

`GET /v1/markets`

The markets listings are covered on: the US directory and each exchange outside the US, with the exchange codes its listings are named under, its main currency, its regular session in local time, and how many listings `/v1/listings` returns for it. Counts refresh hourly. Pass a `country` as `market`, or one of `marketIdentifierCodes` as `exchange`, on [Listings](#listings).

**Parameters:** none.

```bash
curl "https://api.equibles.com/v1/markets" \
  -H "Authorization: Bearer eq_your_api_key"
```

```python
import requests
r = requests.get(
    "https://api.equibles.com/v1/markets",
    headers={"Authorization": "Bearer eq_your_api_key"},
)
print(r.json())
```

```javascript
const res = await fetch("https://api.equibles.com/v1/markets", {
  headers: { Authorization: "Bearer eq_your_api_key" },
});
console.log(await res.json());
```

```json
{
  "data": [
    { "code": "us", "name": "United States", "country": "US", "marketIdentifierCodes": [], "currency": "USD",
      "timeZone": "America/New_York", "sessionOpen": "09:30", "sessionClose": "16:00", "listingCount": 15967 },
    { "code": "euronext-lisbon", "name": "Euronext Lisbon", "country": "PT", "marketIdentifierCodes": ["XLIS", "ENXL", "ALXL"],
      "currency": "EUR", "timeZone": "Europe/Lisbon", "sessionOpen": "08:00", "sessionClose": "16:30", "listingCount": 43 },
    { "code": "xetra", "name": "Xetra", "country": "DE", "marketIdentifierCodes": ["XETR"], "currency": "EUR",
      "timeZone": "Europe/Berlin", "sessionOpen": "09:00", "sessionClose": "17:30", "listingCount": 439 }
  ]
}
```

## Stock profile

`GET /v1/stocks/{ticker}`

One listing and the company behind it: the description, website, sector and industry, SEC CIK, LEI and fiscal year end, the security's ISIN and type, and the company's other listings on every covered exchange, main listing first. Fields with nothing on record are `null`; `fiscalYearEnd` (`MM-dd`) is absent then.

**Parameters:** `{ticker}` (path — exact listed symbol, e.g. `AAPL` or `BRK-B`, or `MIC:TICKER` such as `XETR:SIE`). An unknown listing returns `404`.

```bash
curl "https://api.equibles.com/v1/stocks/XETR:SIE" \
  -H "Authorization: Bearer eq_your_api_key"
```

```python
import requests
r = requests.get(
    "https://api.equibles.com/v1/stocks/XETR:SIE",
    headers={"Authorization": "Bearer eq_your_api_key"},
)
print(r.json())
```

```javascript
const res = await fetch("https://api.equibles.com/v1/stocks/XETR:SIE", {
  headers: { Authorization: "Bearer eq_your_api_key" },
});
console.log(await res.json());
```

```json
{
  "ticker": "XETR:SIE",
  "exchange": "XETR",
  "market": "DE",
  "currency": "EUR",
  "isin": "DE0007236101",
  "companyName": "Siemens Aktiengesellschaft",
  "securityType": "Unknown",
  "primary": true,
  "exchangeTradedProduct": false,
  "description": null,
  "website": "https://www.siemens.com/",
  "sector": "Industrials",
  "industry": "Specialty Industrial Machinery",
  "cik": null,
  "lei": "W38RGI023J3WT1HWRP32",
  "otherListings": []
}
```