Getting started with Initial State starts with learning how to stream your own data into your account. There are multiple ways to do this (e.g. JSON, SDKs, URL parameters, ...). Let's start with a simple, quick way to stream real data into your account - streaming via URL parameters. Step 1 will take less than two minutes, but don't stop here because the really cool stuff happens in steps 2-4!
Create a Data Bucket
When you sign in for the first time, your workspace will look similar to the above screenshot. To create a streaming data bucket, click on the +cloud_icon near the top left (at the top of the bucket shelf).
This will open up a dialog box similar to the one above. You can rename your data stream to whatever you want in the Name field. Every streaming data bucket will have two keys associated with it, the Bucket Key (randomly generated but you can make it whatever you want in this dialog box) and your private streaming Access Key. With these two keys, any device or application can stream data into this data bucket (write only, these keys do not provide the right to read or access data). Click on the Create button at the bottom of the screen to complete the creation of a streaming data bucket.
Stream Data via URL Parameters
Once a new data bucket has been created, your bucket shelf will automatically update as shown above. To stream data into this data bucket, we need the API Endpoint URL. Click on the settings link under the bucket name in the bucket shelf. Copy the text in the API Endpoint section and paste it into your favorite text editor.
In the example above, the text I copied looks like the following:
https://groker.init.st/api/events?accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE&bucketKey=J9GGK8SP3Q96
Let's break down what is in this URL. The first part is the Streaming API endpoint:
https://groker.init.st/api/events
The rest are URL parameters. There are two parameters, accessKey:
accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE
and bucketKey:
bucketKey=J9GGK8SP3Q96
Your URL will have your accessKey and your bucketKey listed. To stream data into this data bucket, we simply need to add additional URL parameters to specify an event/data stream name and corresponding value. Add "&myNumber=1" to your URL (don't copy mine):
https://groker.init.st/api/events?accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE&bucketKey=J9GGK8SP3Q96&myNumber=1
Paste your complete URL to the address bar of your browser and hit enter (or use the 'curl' command at a command prompt) to send the event, "1", to the stream, "myNumber", in your new data bucket.
Click on the bucket name to open it in Tiles. A new Tile named myNumber should have appeared with the value of "1" displayed. Congratulations! You have successfully streamed your first data point in and viewed it in a dashboard.
You can send data to this stream again using the same URL but changing the value of myNumber:
https://groker.init.st/api/events?accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE&bucketKey=J9GGK8SP3Q96&myNumber=2
Repeat this step sending as many values into the myNumber stream as you want. Notice a line graph is automatically drawn, updating in real-time as you send in each new data point.
Next, create a new data stream but instead of numbers, let's use strings or messages as the values. Replace myNumber=2 with myMessage=hi :
https://groker.init.st/api/events?accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE&bucketKey=J9GGK8SP3Q96&myMessage=hi
A new tile named myMessage should have been added to your dashboard with a value being displayed of "hi". Notice how the dashboard tiles are getting automatically added and resized. We will get to how to edit this layout in step 2.
You can send an emoji in as your message, either directly from the emoji unicode or from an emoji token (more information). For example, stream :fire: as the value of myMessage:
https://groker.init.st/api/events?accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE&bucketKey=J9GGK8SP3Q96&myMessage=:fire:
Notice the emoji token, :fire:, is replaced by the actual fire emoji.
Next, create a new data stream called myLocation and send GPS coordinates into it. You can get valid GPS coordinates by going to Google Maps and copying the latitude,longitude values from the URL. For example, 36.1628161,-86.7801636 (no spaces in between the lat/long value):
https://groker.init.st/api/events?accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE&bucketKey=J9GGK8SP3Q96&myLocation=36.1628161,-86.7801636
A new map tile should have been automatically added to your dashboard with a point on the map corresponding to the GPS coordinate sent. If you send multiple GPS coordinates, a path will be automatically drawn for each coordinate:
You can send multiple data points in at the same time by using multiple URL parameters, each separated by &
https://groker.init.st/api/events?accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE&bucketKey=J9GGK8SP3Q96&myNumber=11&myMessage=Error&myLocation=36.1628161,-86.7801636
Reading Data through the Read API
You can read the latest value from any data streamed in through the Read API (more info). You first have to enable read access by going to the bucket settings and checking the "Allow Read Latest Value API" box. The URL for reading your data will be displayed in the box below this checkbox once enabled. In this example, the URL looks like the following:
https://api.init.st/data/v1/events/latest?accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE&bucketKey=J9GGK8SP3Q96
Let's break down what is in this URL. The first part is the Read API endpoint:
https://api.init.st/data/v1/events/latest
The rest are URL parameters. There are two parameters, accessKey:
accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE
and bucketKey:
bucketKey=J9GGK8SP3Q96
Your URL will have your accessKey and your bucketKey listed. To read data from this data bucket, we simply need to copy and paste this URL into the address bar in the web browser. This will return a JSON object with the latest value and timestamp in epoch from every data stream in the data bucket. For example:
{
"myLocation":{
"value":"36.1628161,-86.7801636",
"epoch":1603206668.628336
},
"myMessage":{
"value":":fire:",
"epoch":1603206650.9848
},
"myNumber":{
"value":"11",
"epoch":1603205900.545863
}
}
You can add additional URL parameters to only return data/timestamps from specific event/data streams. Add "&key=myNumber" to your URL (don't copy mine):
https://api.init.st/data/v1/events/latest?accessKey=ist_opLOlZf65uOc-Lw-l_4axCHxA_sIXDGE&bucketKey=J9GGK8SP3Q96&key=myNumber
This will return:
{
"myNumber":{
"value":"11",
"epoch":1603205900.545863
}
}
Other Ways to Stream Data
This step walked you through streaming via URL parameters or the "Events no-JSON" method (officially documented here) and reading data via the Read API (officially documented here). If you want to buffer events and set timestamps, you can stream data via JSON (officially documented here). There are SDKs that abstract the API for languages such as Python and NodeJS to make streaming super easy to implement in your project. There are even completely codeless integrations that stream data such as the Initial State data marketplace (more info).
Comments
0 comments
Please sign in to leave a comment.