Exploring the lemon.markets instruments endpoint
Tags: api, programming, trading, algotrading
Published: 2022-01-21 14:35:20

At [lemon.markets](https://lemon.markets), we’re empowering developers to take brokerage into their own hands by building Europe’s first trading API. In today’s article, we want to showcase one of the useful endpoints we provide: `/instruments`. It can be used to identify the various financial instruments that can be traded on lemon.markets, such as stocks and ETFs.

---

The lemon.markets API currently offers 8250+ popular stocks and ETFs — we’ve got (most 😉) big-name instruments. Not sure if we carry a particular listing? You can easily use the '/instruments' endpoint to search for specific financial instruments. Want to see how it’s done? Let’s jump right in.

## Why search for my financial instrument? 🔎
If you already know the name of the financial instrument you wish to trade, why should you use the `/instruments` endpoint? Our API identifies financial instruments through an ISIN (International Securities Identification Number). If you know the ISIN of the instrument you wish to trade, you’re ready to place your order! But, if you don’t, you can use this endpoint to find the ISIN associated with that instrument.

Besides the ISIN, the `/instruments` endpoint also provides information about:

- the exchange the instrument is listed on,
- the symbol, WKN and title associated with the instrument,
- the type of instrument you’re dealing with (stock/ETF/etc.),
- in which currency the instrument is traded and
- whether it’s currently tradable.

This information allows you to double-check that you’re referring to the correct instrument, on the correct exchange, in the correct currency. Additionally, only placing orders if the instrument is currently tradable (and the exchange on which it’s traded is open), will ensure that you have no surprise unexecuted orders.

## The /instruments endpoint 🎺

To access the /instruments endpoint, you’ll need to use the following URL:

``` python
https://data.lemon.markets/v1/instruments/
```

In Python, a `GET` request using this URL looks as follows (note: we have sample code snippets in JavaScript in our [docs](https://docs.lemon.markets/market-data/instruments-tradingvenues#get-instruments)):

```python
import requests

response = requests.get("https://data.lemon.markets/v1/instruments/", 
                        headers={"Authorization": f"Bearer YOUR-API-KEY"})

print(response.json())
```
<figcaption>If you’d like to use this code snippet, you’ll have to insert your own API key.
</figcaption>


Without any search specifications, this endpoint will return all of the instruments that can be traded with the lemon.markets API (only a very short portion of the response is listed). Perhaps this is useful if you’re simply browsing what we have on offer. But, what if you’re looking for something specific?

## Specifying your search ➡️

Imagine you’re looking for the ISIN that belongs to Coinbase. How do we alter the search? There’s a number of query parameters that can be added to the end of the URL. These are:

- `search`, search query for a name, title, ISIN, WKN or symbol (note: your query must be longer than 4 characters),
- `isin`, if you know the ISIN of the instrument you’re looking for (you can specify up to 10 different ISINs if you’re looking for more than one),
- `mic`, the Market Identifier Code of the exchange you wish to trade on,
- `currency`, ISO currency code for the currency in which you’d like to trade and
- `tradable`, a boolean value to filter for tradable and non-tradable instruments.

Besides that, if your API result contains several entries, you can paginate through the response using the pagination parameters `limit` and `page`. If you’d like to learn more, you can find the details [here](https://docs.lemon.markets/market-data/overview#pagination-in-the-market-data-api).

In our case, we’re interested in specifying `search` because we know the title of the instrument we’re looking for. And let’s specify `tradable` because we only wish to return instruments that can be traded. This means the URL against which we place the request turns into:

```
https://data.lemon.markets/v1/instruments/?search=coinbase&tradable=true
```

The request is placed in the same way as in the above code sample. The API outputs the following response:

``` json
{
    "results": [
        {
            "isin": "US19260Q1076",
            "wkn": "A2QP7J",
            "name": "COINBASE GLB.CL.A -,00001",
            "title": "COINBASE GLOBAL INC.",
            "symbol": "1QZ",
            "type": "stock",
            "venues": [
                {
                    "name": "Börse München - Gettex",
                    "title": "Gettex",
                    "mic": "XMUN",
                    "is_open": true,
                    "tradable": true,
                    "currency": "EUR"
                }
            ]
        }
    ],
    "previous": null,
    "next": null,
    "total": 1,
    "page": 1,
    "pages": 1
}
```

Note that the `results` list now only contains one instrument because we specified our query with enough detail to narrow down the search. We can now use this ISIN to [place trades with the Trading API](https://medium.com/lemon-markets/placing-your-first-order-with-the-lemon-markets-trading-api-bcada2472b6e).

---

That’s all there is to know about the `/instruments` endpoint! We hope it was helpful in exploring what can be done with lemon.markets. If you’re not yet signed-up, [join us](https://dashboard.lemon.markets/signup) today!

Joanne from 🍋.markets