Readiness.IO

Getting started

If you have an account with a channel, there's nothing to set up, just start sending data to your channel on a topic in single entry JSON format.

You don't need to pre-define your topics, you can just start sending data to any topic name as long as that name is a valid URL.

[channel].v1.readiness.io/[topic]/?[filters|transforms]

Saving data

POST

https://{{ channel }}.v1.readiness.io/my-topic

POST requests should contain a JSON encoded body with the Content-Type: application/json header, or a URL encoded body with the Content-Type: application/x-www-form-urlencoded header. Successful posts will return with a 201 response code.

PAYLOAD

  {
    reading: 123,
    name: "My cool device"
  }

If you are using WebSockets from a browser, connect to the WebSocket URL and publish your message.

PUBLISH

ws://{{ channel }}.v1.readiness.io/my-topic

Returning or receiving data

To read that data again, GET or subscribe to that same address. Please note, be design, Readiness.IO only returns one row for a request. If you want a larger sample set of your data please see the filtering section.

GET

https://{{ channel }}.v1.readiness.io/my-topic

If you are using WebSockets from a browser, connect to the WebSocket URL and subscribe to messages.

SUBSCRIBE

ws://{{ channel }}.v1.readiness.io/my-topic

Deleting data

You can permanently remove single or multiple data entries from a topic in the datastore using the DELETE method. This method is only available via REST verbs and requires supplying an API key by default.

Delete a single entry using the inserted_at time (you'll need to know the inserted_at time from a GET request first)

DELETE

{{ channel }}.v1.readiness.io/my-topic?inserted_at=1539679588942&apikey=...

Delete multiple entries using filters

DELETE

channel.v1.readiness.io/topic?since=1 day ago&limit=10&apikey=...

Delete an entire topic

DELETE

channel.v1.readiness.io/topic?apikey=...

Time and Quantity

If you want more than 1 row returned, you must always supply a time and/ or quantity based filter as well.

By default, only the most recent single data entry will be returned. If you want to load additional data, you can use the limit, since, and/or until filters. Both since and until support multiple time formats and relative times (see additional documentation on time formats here at chrono-node). When using relative times, you can specify the UTC offset in hours, minutes, or a timezone code (eg 10 or 600 or AEST, -5 or -300 or EST) using the tz query. If not tz is specified, UTC time will be assumed. Readiness.IO does not adjust for daylight savings, and as such you must specify the correct timezone based on wether you are in daylight savings or not (eg AEST vs AEDT). Get the latest entry from a topic as an object

{{ channel }}.v1.readiness.io/topic

Get as much data as possible since Jan 1 2019 UTC time as an array (maximum 1000 rows)

{{ channel }}.v1.readiness.io/my-topic?since=1546304460

Get data between Jan 1 2018 UTC and Jan 1 2019 UTC using Javascript Timestamps

{{ channel }}.v1.readiness.io/my-topic?since=1514772000000&until=1546308000000

Get data between Jan 1 2018 UTC and Jan 1 2019 UTC using a friendly date format

{{ channel }}.v1.readiness.io/my-topic?since=Jan 1 2018&until=Jan 1 2019

Retrieve data for the last 7 days

{{ channel }}.v1.readiness.io/my-topic?since=7 days ago

Retrieve data since midnight using the +10 timezone offset (AEST)

{{ channel }}.v1.readiness.io/my-topic?since=today midnight&tz=10

Retrieve data for the previous business week in a timezone using the timezone name

{{ channel }}.v1.readiness.io/my-topic?since=last monday midnight&until=last saturday midnight&tz=AEST

Retrieve the last 50 entries from a topic as an array

{{ channel }}.v1.readiness.io/my-topic?limit=50

Queries

Both HTTP and WebSockets (and MQTT soon) can perform a series of powerful data transformation actions on the data server-side before its saved or sent by specifying the ?q= querystring in your request or connection. Queries are executed in the order they are written, and can be chained together to run multiple actions using a semicolon ;. Parameters can optionally be provided to each query by including them in a pair of parentheses immediately after the queries name.

Sending two queries

{{ channel }}.v1.readiness.io/my-topic/?q=firstQuery;secondQuery;

Sending two queries with and without parameters

{{ channel }}.v1.readiness.io/my-topic/?q=firstQuery(first_parameter,second_parameter);secondQuery();

Many queries require more than one data entry to be useful, so you likely will need to use limit, since, and/or until for GET requests.

{{ channel }}.v1.readiness.io/my-topic/?limit=1000q=sort(reading);head(5);

Queries: Head, Tail, Splice

Head, Tail and Splice return a number of results from the top, bottom or specific point in the dataset.

Return the first 5 values from a collection of 10

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=head(5)

Return the last 5 values from a collection of 10

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=tail(5)

Starting at the 5th item, return 3 items from a collection of 10

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=splice(5,3)

Queries: Filters

You can remove results that do not meet certain criteria from your results by specifying a filter query. There are a number of filtering operators, which can be combined using special AND and OR symbols, and some operators support comparing multiple values at once.

Operator	Operation	Multiple Value Support
:	Equals	Yes, Equals any
!:	Not Equals	Yes, Equals none
<	Less than	No
<:	Less than or equals	No
>	Greater than	No
>:	Greater than or equals	No

Check if a field equals a specific value

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(fieldname:value)

Check if a field is not equal to a specific value

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(fieldname!:value)

Check if a field is greater than a specific value

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(fieldname>value)

Check if a field is less than or equal to a specific value

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(fieldname<:value)

Combining filters

There are multiple ways you can chain multiple filters together depending on your needs. In order of their operation, you can:

Use a pipe | to compare a single field against multiple values (OR when using equals, AND when using not equals)
Use a plus + to compare if multiple statements are true (AND)
Use a comma , to send additional parameters, evaluating will stop once one parameter is true (OR)
Use a second filter() function to filter the data again (AND)

Check if a fields equal one of the specific values. (a=b OR a=c)

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a:x|y);

Check two fields equal the specific values. (a=b AND b=y)

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a:x+b:y);

Check two fields equal one of the specific values. (a=b AND (b=y OR b=z))

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a:x+b:y|z);

Check two fields do not equal one of the specific values. (a!=b AND (b!=y AND b!=z))

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a!:x+b!:y|z);

Check two fields do not equal one of the specific values. (a!=b AND (b!=y AND b!=z))

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a!:x+b!:y|z);

Check if either two fields equal the specific values. (a=x OR b=y)

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a:x,c:y);

Check if either two fields equal one of the specific values. (a=x OR (b=y OR b=z)

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a:x,c:y|z);

Check if either the first fields equal a value, or the second field equals that value while the first equals one of the other values. (a=x OR ((a=y OR a=z) AND b=x))

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a:x,a:y|z+b:x);

Check if either the first fields equal a value, or the second field equals that value while the first equals one of the other values. (a=x OR ((a=y OR a=z) AND b=x))

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a:x,a:y|z+b:x);

Check if one field is a value, and a second field is a value or two other fields have the same value. (a=x AND (b=x OR (c=y AND d=y)))

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a:x);filter(b:x,c:y+d:y);

This example uses all four methods in a single query. (a=x AND (b=x OR (c=y AND (d=y OR d=z))))

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(a:x);filter(b:x,c:y+d:y|z);

Check if a fields value is between two numbers

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(reading>0+reading<10);

Check if a fields value is between or equal to two numbers

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=filter(reading>:0+reading<:10);

Sorting

Data can be sorted by string comparison in ascending or descending order using the sort query and one or more field names as parameters. Sorting is in ascending order by default, but can be set to descending by adding a - to the front of the field name.

Get the latest 10 entries then sort by the value of the age field

{{ channel }}.v1.readiness.io/my-topic/?limit=10&q=sort(age)

Sort fields can be chained together by comma separating them.

{{ channel }}.v1.readiness.io/my-topic/?q=sort(age,-height)

Combine the Sort and Head queries if you need a more flexiblilty than min or max

{{ channel }}.v1.readiness.io/my-topic/?q=sort(-reading,inserted_at);head(1)

{{ channel }}.v1.readiness.io/my-topic/?

Time series

Data can be aggregated over a set timespan using the timeseries query. You must first specify the timespan that the data will be grouped by, then any number of statistical functions and fields you wish to apply to each group in a comma seperated list.

Time spans

Timespans can be specified in days, hours, minutes, seconds, or milliseconds

1d or 1 day
24h or 24 hours
30m or 30 minutes
90s or 90 seconds
2500ms or 2500 milliseconds

Statistical functions

Each statistical function consists of a function name and the field to apply that function to. The syntax changes for some functions depending on whether a field name is optional

count (field optional)
sum
avg
max
min

Get a count of entries for each day over the last 7 days.

{{ channel }}.v1.readiness.io/my-topic/?since=7 days ago&q=timeseries(1d,count)

Get a count of entries where the 'reading' field exists for each hour over the 24 hours.

{{ channel }}.v1.readiness.io/my-topic/?since=24 hours ago&q=timeseries(1h,count:reading)

Get a sum of readings for each hour since midnight AEST.

{{ channel }}.v1.readiness.io/my-topic/?since=today midnight&tz=10&q=timeseries(1 hour,sum:reading)

Get the min, max, and average of reading, and the earliest timestamp for each minute for the past hour.

{{ channel }}.v1.readiness.io/my-topic/?since=1 hour ago&tz=10&q=timeseries(1 min,min:reading,max:reading,avg:reading,min:inserted_at)

{{ channel }}.v1.readiness.io/my-topic/?

Format transforms

Readiness.IO can do complex translations between stored, submitted and requested data formats. This includes field name changes, math functions and object nesting according to supported formats.

If a vendor specifies that they are Readiness.IO compliant, they will typically also let you know of their vendor specific format transform which you can add on to the end of the url.

Invoking a format transform on data

{{ channel }}.v1.readiness.io/my-topic/?q=agriwebb-rain-gauge

Custom queries

Readiness.IO supports custom queries for channels and vendors.

custom queries consist of an input and output definition and are chainable like any other filter

If you need a custom query, please let the Readiness.IO development team know.

Security

Readiness.IO uses API keys to lock down some methods. By default CREATE and READ does not require an API key but can be configured to use one on a per topic or channel level. DELETE requires an API key. There is no UPDATE verb.

To send an API key with your request, add it to the querystring.

GET

https://{{ channel }}.v1.readiness.io/my-topic/?apikey=...

If the channel is disabled, or an API key is required, you will receive a 403 responsecode. If the rate limit has been exceeded, you will receive a 429 response code.

Default limits for dedicated accounts

Readiness.IO imposes the following limits by default.

              
{
   "disabled": false,              // Disable the channel entirely and return 403 to every request
   "ratelimits": {
       "bypass": false,            // This completely disables rate limiting when true
       "topicLimit": 255,          // The maximum number of topics per channel
       "dataLimit": 2048,          // The maximum number of entries per topic
       "topicWriteLimit": 16,      // Maximum number of writes in the time period per topic
       "topicWritePeriod": 1000,   // Time period for maximum number of writes per topic
       "topicReadLimit": 16,       // Maximum number of REST reads in the time period per topic
       "topicReadPeriod": 1000,    // Time period for maximum number of REST reads per topic
       "channelWriteLimit": 64,    // Maximum number of writes in the time period per channel
       "channelWritePeriod": 1000, // Time period for maximum number of writes per channel
       "channelReadLimit": 64,     // Maximum number of REST reads in the time period per channel
       "channelReadPeriod": 1000,  // Time period for maximum number of REST reads per channel
       "channelListenerLimit": 64, // Maximum number of listeners per channel
       "topicListenerLimit": 8     // Maximum number of listeners per topic
   },
   "querylimits": {
       "getDefault": 100,          // Default number of items loaded from disk when since or until is specified
       "getMaximum": 1000          // Maximum number of items the user can ask to load from disk
   },
   "apikeys": {
       "read": null,               // This channel can be read publicly
       "write": ["abc"],           // This channel requires the specified API key to write
       "delete": ["abc","xyz"],    // This channel requires either of the specified API key to delete
       "topics": {
           "secret": {
               "read": ["super"],  // This topic requires this API key, despite the channel configuration 
                                   // This topic will use the channels 'write' API key as its not defined on the topic
               "delete": null      // This topic allows public delete, this is not smart.
           }
       }
   },
   "email": {
       "domains": ["test.com"]     // Domains this channel can send emails as
   }
}

Realtime Rapid API Documentation Welcome channel owner {{ channel }}

Getting started

Saving data

Returning or receiving data

Deleting data

Time and Quantity

Queries

Queries: Head, Tail, Splice

Queries: Filters

Combining filters

Sorting

Time series

Time spans

Statistical functions

Format transforms

Custom queries

Security

Default limits for dedicated accounts

Realtime Rapid API Documentation

Welcome channel owner {{ channel }}