[Tutorial] Retrieve data from a web API in Valkyrie

Learn how to create an app that retrieves bitcoin USD value on the web

This is a simple example of an advanced functionality of Valkyrie Engine, where you will learn how to pull data from the web and display it in your scene.

I will use a publicly available API that requires neither registration nor API key and displays parameters of various cryptocurrencies: https://www.coinlore.com/cryptocurrency-data-api

Here is an example of the GET request method I am going to use for illustrative purposes: https://api.coinlore.com/api/ticker/?id=90
This request will return the following properties and values:

id “90”
symbol “BTC”
name “Bitcoin”
nameid “bitcoin”
rank 1
price_usd “11946.72”
percent_change_24h “0.12”
percent_change_1h “0.99”
percent_change_7d “14.00”
market_cap_usd “213235242029.04”
volume24 “17003508444.32”
volume24_native “1423278.92”
csupply “17848859.00”
price_btc “1.00”
tsupply “17848859”
msupply “21000000”

Now let’s implement this in Valkyrie.

How to create a GET request method in Valkyrie

I start with a new level:

Then do a bit of cleanup:
API call level

I add a Text entity that I name “Bitcoin display”, where I will display the USD value of a Bitcoin:
Text entity
Notice that in the Text entity, you have a “text” property which will be used to receive the bitcoin value later on:
text property

I add a DataTable entity that will receive all the data pulled from the API:
DataTableReadURL

Now we have 2 actions to add to the Timeline and we are all set.

DataTableReadURL

First I drag&drop a DataTableReadURL action, which will allow me to call the API, onto the DataTable entity:

I then set the DataTableReadURL properties:

  • in the start_time field I enter a value of 1 second (on the Timeline, the actions positioned at 0 second are only triggered once)
  • in the url field I input the HTTP GET request (in this scenario: https://api.coinlore.com/api/ticker/?id=90)
  • in the target field I input the DataTable where the API result will be updated (in this scenario, my table is named “DataTable”)
    DataTableReadURL properties

EntitySetProperty

Lastly, I drag&drop the entity EntitySetProperty, which will allow me to change the properties of my Text entity, onto the DataTable entity:
EntitySetProperty

I then set the EntitySetProperty properties:

  • in the start_time field I enter a value of 6 seconds because I want to leave 5 seconds to the DataTableReadURL to fetch the bitcoin value on the web
  • in the target field I set the name of the Text entity I will be updating with the returned value (in this scenario “Bitcoin display”)
  • in the property field I enter the property of the Text entity I want to update, as we saw a bit earlier, we want to update the text property
  • in the type field, I set String
  • in the start_expr field I set the following string to signify which property of my DataTable I want to retrieve:
    "dt://" + Name of DataTable (in this scenario “DataTable”) + “/@” + DataTable property (in this scenario “price_usd”)
    Which gives me the value dt://DataTable/@price_usd
    EntitySetProperty properties

This is it, I just created an app that will retrieve the USD bitcoin value in real-time from a web API:

Downloads

  • Download the tutorial project (VLK file) Here (2.1 KB).
  • Download the end result (VPK file) Here (3.1 KB).

Note that it can take a little time before the USD value of the bitcoin is refreshed. These parameters depend on the API provider.

Limitations

You can do any HTTP GET request which receives a flat JSON object as response.
If you need to process complex APIs (APIs that respond with deep hierarchies or arrays), you will need to create a small proxy server to provide a clean HTTP interface to your Valkyrie application.

2 Likes