Introduction to the Coinranking API

Introduction to the Coinranking API

As most developers may know, "API" stands for Application Programming Interface. These types of software interfaces have become the centre of software development. They are responsible for transferring real-time data to developers, products, and end-users.

What's more, cryptocurrency data is arguably one of the most sought after information worldwide, that being the case, in this article, we would be documenting a freemium cryptocurrency API called Coinranking. This API can be utilized to add real-time prices of cryptos like Bitcoin, Ethereum, Dogecoin, etc. Get metadata on every major coin listed on the API, such as market capitalization, circulating supply, logos and even coin history.

Getting Started

The Coinranking API consists of a free plan and also a PRO plan. Whichever plan you would be using, a unique API key is needed, hence, create an account and generate an API key here.

The PRO plan gives access to more endpoints and API calls but getting started, the free plan is sufficient.

In this article, we would be using Axios. Axios is a JavaScript library used to make HTTP requests from Node.js or XMLHttpRequests from the browser. It is easy to use and can be utilized in any kind of web project.

Base Url

https://api.coinranking.com/v2

Headers Parameters

These parameters are compulsory to make a successful request, they are included in the Headers object of your Axios request.

Base Url: https://api.coinranking.com/v2

API key: your unique API key

Getting Multiple Coins

"Coins" are all the cryptocurrencies listed on the API such as Bitcoin, Ethereum, XRP and many more. The coins are listed in order of ranks, which is determined by their market cap. Therefore, a coin like Bitcoin would appear before any other coin by default.

To get the list of coins, a GET request is sent with the /coins attached to the base Url. The parameters for querying the coins depending on the information you wish for are listed below.

Query Parameters

Parameter NameTypeDescription
referenceCurrencyUuid (optional)StringUUID of reference currency, in which all the prices are calculated. This includes the price, the change and the sparkline. Defaults to US Dollar

Default value: yhjMzLPhuIDl
timePeriod (optional)StringBy setting the timeperiod the change percentage and sparkline in the response will be calculated accordingly

Default value: 24h
Allowed values:3h 24h 7d 30d 3m 1y 3y 5y
symbols (optional)ArraySymbols to filter the list on.
uuids (optional)ArrayUUIDs to filter the list on. If you know the UUIDs of the coins you want to fetch, you can use this filter to get the specific coins.
tiers (optional)ArrayWe seperate coins into three tiers. With this parameter you can filter coins on the tiers you need. Read more about out our tiers in our methodology
tags (optional)ArrayTags to filter the list on.

Allowed values: defi stablecoin nft dex exchange staking dao meme privacy
orderBy (optional)StringIndex to order by. All sortings excluding listedAt still take our different tiers of coins into account, read more about it in our methodology.

Default value: marketCap
Allowed values: price marketCap 24hVolume change listedAt
search (optional)StringFilter the results by searching for coin names or symbols.
orderDirection (optional)StringApplies direction to the orderBy query, which can be in ascending or descending order.

Default value: desc
Allowed values: desc asc
limit (optional)NumberLimit. Used for pagination.

Default value: 50
Size range: 0-100
offset (optional)NumberOffset. Used for pagination.

Default value: 0

Therefore, to fetch the list of coins using the Axios library and JavaScript as our language, the code snippet should look something like this:

import axios from "axios";

const options = {
  method: 'GET',
  url: 'https://api.coinranking.com/v2/coins',

  headers: {
    'x-access-token': '<your api key>'
  }
};

axios.request(options).then(function (response) {
    console.log(response.data);
}).catch(function (error) {
    console.error(error);
});

The above Axios code is expected to return the list of all cryptocurrencies.

Parameter Example

import axios from "axios";

const options = {
  method: 'GET',
  url: 'https://api.coinranking.com/v2/coins',
  params: {
    referenceCurrencyUuid: 'Qwsogvtv82FCda',
    timePeriod: '24h',
    tiers: '1',
    orderBy: 'marketCap',
    orderDirection: 'desc',
    limit: '50',
    offset: '0'
  },
  headers: {
    'x-access-token': '<your api key>'
  }
};

axios.request(options).then(function (response) {
    console.log(response.data);
}).catch(function (error) {
    console.error(error);
});

Response

The above request is expected to return the Bitcoin cryptocurrency alongside its total coins, markets, exchanges, market caps and 24-hour volume in JSON format. Other cryptocurrencies would also be returned as well in the same format, and order of their market cap.

HTTP/1.1 200 OK
{
  "status": "success",
  "data": {
    "stats": {
      "total": 3,
      "totalCoins": 10000,
      "totalMarkets": 35000,
      "totalExchanges": 300,
      "totalMarketCap": "239393904304",
      "total24hVolume": "503104376.06373006"
    },
    "coins": [
      {
        "uuid": "Qwsogvtv82FCd",
        "symbol": "BTC",
        "name": "Bitcoin",
        "color": "#f7931A",
        "iconUrl": "https://cdn.coinranking.com/Sy33Krudb/btc.svg",
        "marketCap": "159393904304",
        "price": "9370.9993109108",
        "btcPrice": "1",
        "listedAt": 1483228800,
        "change": "-0.52",
        "rank": 1,
        "sparkline": [
          "9515.0454185372",
          "9540.1812284677",
          "9554.2212643043",
          "9593.571539283",
          "9592.8596962985",
          "9562.5310295967",
          "9556.7860427046",
          "9388.823394515",
          "9335.3004209165",
          "9329.4331700521",
          "9370.9993109108"
        ],
        "coinrankingUrl": "https://coinranking.com/coin/Qwsogvtv82FCd+bitcoin-btc",
        "24hVolume": "6818750000"
      }
    ]
  }
}

Querying a particular parameter in the JSON response object should give you specific information. For example:

data.coins.price: Price of the coin

data.coins.symbol: Currency symbol

Error Response

Not every API call ends up successful, error responses could occur when there is something wrong with your request or the API could not parse the passed data.

The error responses possible while using the /coins endpoint are 422 errors:

Error NameTypeDescription
VALIDATION_ERRORObjectThe request could not be validated. The response should provide more details.
REFERENCE_UNAVAILABLEObjectThe reference currency used in the request is not available. Choose another UUID.

Getting a Specific Coin

To receive information about a specific coin, the /coin/:uuid parameter comes in handy. The UUID of a coin is a string value that can be found using the coins endpoint.

It can also be obtained by visiting coinranking.com, then clicking on the particular cryptocurrency, and copying its UUID. For instance, coinranking.com/coin/razxDUgYGNAdQ+ethereum.. is the URL for Ethereum, and razxDUgYGNAdQ is its UUID.

Query Parameters

Parameter NameTypeDescription
referenceCurrencyUuid (optional)StringUUID of reference currency, in which all the prices are calculated. Defaults to US Dollar

Default value: yhjMzLPhuIDl
timePeriod (optional)StringTime period where the change and sparkline are based on

Default value: 24h
Allowed values: 24h 7d 30d

Using the Axios library, alongside the optional query parameters to fetch the Ethereum coin, we have:

import axios from "axios";

const options = {
  method: 'GET',
  url: 'https://api.coinranking.com/v2/coin/razxDUgYGNAdQ',
  params: {referenceCurrencyUuid: 'yhjMzLPhuIDl', timePeriod: '24h'},
  headers: {
    'x-access-token': '<your api key>'
  }
};

axios.request(options).then(function (response) {
    console.log(response.data);
}).catch(function (error) {
    console.error(error);
});

Response

200 OK
{
2 items
"status":"success"
"data":{1 item
"coin":{24 items
"uuid":"razxDUgYGNAdQ"
"symbol":"ETH"
"name":"Ethereum"
"description":"Ethereum (ETH) is a global, public decentralized blockchain"
"color":"#3C3C3D"
"iconUrl":"https://cdn.coinranking.com/rk4RKHOuW/eth.svg"
"websiteUrl":"https://www.ethereum.org"
"links":[...]9 items
"supply":{...}3 items
"numberOfMarkets":30335
"numberOfExchanges":224
"24hVolume":"13723476496"
"marketCap":"353477263489"
"price":"2953.5950509683876"
"btcPrice":"0.07167845130740841"
"priceAt":1647878580
"change":"3.64"
"rank":2
"sparkline":[...]27 items
"allTimeHigh":{...}2 items
"coinrankingUrl":"https://coinranking.com/coin/razxDUgYGNAdQ+ethereum-eth"
"tier":1
"lowVolume":false
"listedAt":1438905600
   }
}

Error Response

The possible error response peculiar to this particular endpoint is a 404 and a 422 error:

404

Error NameTypeDescription
COIN_NOT_FOUNDObjectThe coin could not be found. Try another UUID

422

Error NameTypeDescription
VALIDATION_ERRORObjectThe request could not be validated. The response should provide more details.
REFERENCE_UNAVAILABLEObjectThe reference currency used in the request is not available. Choose another UUID.

Getting the Coin Price

The /coin/:uuid/price endpoint will return the price of a coin at a specific time alongside its timestamp.

Query Parameters

Parameter NameTypeDescription
referenceCurrencyUuid (optional)StringUUID of reference currency. This is the currency the price is shown in, which defaults to US Dollar

Default value: yhjMzLPhuIDl
timestamp (optional)NumberTimestamp. Epoch timestamp in seconds. If it is not provided this endpoint will get the latest price

To get the price of Ethereum, alongside its timestamp using the Axios library in JavaScript, we have:

import axios from "axios";

const options = {
  method: 'GET',
  url: 'https://api.coinranking.com/v2/coin/razxDUgYGNAdQ/price',
  params: {referenceCurrencyUuid: 'yhjMzLPhuIDl'},
  headers: {
    'x-access-token': '<your api key>'
  }
};

axios.request(options).then(function (response) {
    console.log(response.data);
}).catch(function (error) {
    console.error(error);
});

Response

200 OK
{
 2 items
"status":"success"
"data":{ 
 2 items
"price":"2944.211387631011"
"timestamp":1647879960
   }
}

Error Response

A set of 404 and 422 errors are possible for this particular endpoint.

404

Error NameTypeDescription
PRICE_NOT_FOUNDObjectNo price could be calculated for this request. Try another coin and/or another reference currency
COIN_NOT_FOUNDObjectThe coin could not be found. Try another UUID

422

Error NameTypeDescription
VALIDATION_ERRORObjectThe request could not be validated. The response should provide more details.
REFERENCE_UNAVAILABLEObjectThe reference currency used in the request is not available. Choose another UUID.

Getting a Coin Price History

The Coinranking API keeps track of the price histories of each cryptocurrency listed on it. A GET request to the /coin/:uuid/history endpoint returns this particular piece of data.

Query Parameters

Parameter NameTypeDescription
timePeriod (optional)StringTimeperiod where the change and history are based on

Default value: 24h
Allowed values: 3h 24h 7d 30d 3m 1y 3y 5y
referenceCurrencyUuid (optional)StringUUID of reference currency, in which all the prices are calculated. Defaults to US Dollar

Default value: yhjMzLPhuIDl

An example using Axios in JavaScript:

import axios from "axios";

const options = {
  method: 'GET',
  url: 'https://api.coinranking.com/v2/coin/razxDUgYGNAdQ/history',
  params: {referenceCurrencyUuid: 'yhjMzLPhuIDl', timePeriod: '24h'},
  headers: {
    'x-access-token': '<your api key>'
  }
};

axios.request(options).then(function (response) {
    console.log(response.data);
}).catch(function (error) {
    console.error(error);
});

Response

HTTP/1.1 200 OK
{
  "status": "success",
  "data": {
    "change": "2.52",
    "history": [
      {
        "price": "2927.0769673624704",
        "timestamp": 1647881400
      },
      {
        "price": "2927.7378251530245",
        "timestamp": 1647881100
      }
    ]
  }

Error Responses

Both 404 and 422 errors are possible on this endpoint.

404

Error NameTypeDescription
COIN_NOT_FOUNDObjectThe coin could not be found. Try another UUID

422

Error NameTypeDescription
VALIDATION_ERRORObjectThe request could not be validated. The response should provide more details.
REFERENCE_UNAVAILABLEObjectThe reference currency used in the request is not available. Choose another UUID.

There is a whole lot more information that can be obtained from the Coinranking API. Some of these endpoints are only available in the PRO version, such as the coin exchanges and coin markets data.

However, information such as a coin's OHLC (Open High Low Close) data, coin supply data, coin issuance blockchains and so on can be obtained from the API for free.

Conclusion

Knowing how to work with APIs as a software engineer is as important as water in the desert. Consequently, including an API in your next project would be a game-changer and take your portfolio to the next level. In addition, proper documentation and the technical know-how in documenting APIs is an essential need in the tech industry, the best APIs are usually the well-documented ones. This provides a low barrier for usage and understanding, since not every developer, or end-user possess the same level of skill and experience.

The Coinranking API may be a good fit for your next project. For more information, refer to the official docs.

For a list of APIs you can include in your next project, kindly check out Rapid API hub.

Follow me on Twitter. Happy Coding!

Attributions