Tezos Explorer API Best Practices: #3 Filter data on the API, not on the client


In the previous article we discovered how the select parameter can significantly reduce the amount of transmitted data and response time.

In this article we will explain how you can significantly speed up the performance, and moreover simplify the logic of your application, by using data filtering in the request query to Tezos Explorer TzKT API. It doesn’t matter what kind of application you are developing. It can be a simple baker’s dashboard, a wallet or even an exchange. If you use request-level filtering, you rely on TzKT API logic, which greatly reduces the risk of errors.

Table of contents

Filter data on the Tezos API, not on the client

Each time we request an array of data from the Tezos API, we actually need a very specific small part of the data. Let’s take a look at the simple example when we need just one delegator’s reward payout transaction for the particular cycle. We can simply get all incoming transactions, as, unfortunately, a lot of people do: ...&status=applied

We’ve got 113 transactions, a little bit better, but that’s still not enough.

Obviously, in the vast majority of cases, we only need to look into a specific period of time. Usually it is enough to take a selection only for the previous Tezos block or cycle. In our case we need only one cycle transactions ...&amount.gt=100000&amount.le=1000000

Please, note, all amounts in TzKT API are in microtez

Now we see only one transaction.

And finally, let’s use what we learned from the previous article and add ?select to get only the fields we really need: just contact us, and we’ll do our best to fit your needs!

Advanced request filtering

That’s the beginning of what we want to show! TzKT API provides much more options for data filtering. Let’s dig a little deeper.

Basic modes

In addition to the desctibed above .gt, .ge, .lt and .le basic modes there are aslo .eq and .ne modes, Let's say we need all unsuccessfull operations. For that purpose we can use not equal filtering mode param.ne=123. It helps us to exclude all entities with a particular value. And our request will look like /transactions?sender.in={firstAddress},{secondAddress}

Filter by another field

Also, we may need to filter data not by the particular value(s), but by its “nature”. For example, what if we want to get all operations of baker registration/reactivation? In other words, we need to get the Tezos delegation operations where sender field is equal to newDelegate field. In such cases we can use equal to another field param1.eqx=param2 and not equal to another field param1.nex=param2 filtering modes: /delegations?newDelegate.eqx=sender. Another example is requesting all loop-transfers: /transactions?sender.eqx=receiver.

Check on null

If it’s suitable, don’t hesitate to use the null check parameter in your requests. Let's consider we need only delegation cancelation operations: /delegations?prevDelegate.null=false&newDelegate.null=true

&newDelegate.null=true can be simplified/shortened to &newDelegate.null, without =true.

Wildcard pattern matching

TzKT API allows you to use wildcard pattern matching on transaction parameters. This is helpful when you need to filter smart contract calls. For example, if we need to get a particular token’s transfers the .as wildcard pattern matching comes to the aid: ...parameters.un=*"entrypoint":"transfer"*

Dealing with batch and internal Tezos operations

Often filtration is not required at all, and we can get the operation we need just by its hash: /operations/{hash}

If it is a batch operation, you can use the counter of a specific operation within the batch to avoid requesting all operations when you need only one: /operations/{hash}/{counter}

If the operation contains an internal operation, you can get internal operation by its counter and nonce: /operations/{hash}/{counter}/{nonce}


To sum up, we would like to say that data filtering on the API side has a number of undeniable advantages, such as reduced load on the client application and significantly higher download speed due to a smaller amount of data. We will be very glad if you will use the maximum features of the TzKT API because that’s what it was created for.

What’s next?

This is the third article of series “Tezos Explorer API Best Practices”. In the next article we’ll talk about pagination in API requests.


Originally published at https://baking-bad.org on September 28, 2020.

Also, Read

Get Best Software Deals Directly In Your Inbox

Tezos Explorer API Best Practices: #3 Filter data on the API, not on the client was originally published in Coinmonks on Medium, where people are continuing the conversation by highlighting and responding to this story.