Dweeting

Send data from your thing to the cloud by "dweeting" it with a simple HAPI web API. You can also play with dweet.io using our API console.

To dweet from your thing, simply call a URL like:

https://dweet.io/dweet/for/my-thing-name?hello=world

Getting Dweets

To read the latest dweet for a thing, you can call...

https://dweet.io/get/latest/dweet/for/my-thing-name

Note that dweet.io only holds on to the last 5 dweets over a 24 hour period. If the thing hasn't dweeted in the last 24 hours, its history will be removed.

Or to read all the dweets for a dweeter, you can call...

https://dweet.io/get/dweets/for/my-thing-name

Dweet.io will respond with one or more dweets which look like:

{
  "this": "succeeded",
  "by": "getting",
  "the": "dweets",
  "with": [
    {
      "thing": "my-thing-name",
      "created": "2014-01-15T18:41:17.166Z",
      "content": {
        "this": "is cool!"
      }
    },
    {
      "thing": "my-thing-name",
      "created": "2014-01-15T18:41:01.583Z",
      "content": {
        "hello": "world",
        "foo": "bar"
      }
    }
  ]
}

Getting Stored Dweets

Dweets are stored for up to 1 month if they are locked. You can query a maxiumum 1 day of dweet history per request or as granular as 1 hour. Locks cost $1.99/month.

To get all of a thing's dweets for a given hour:

https://dweet.io/get/stored/dweets/for/{thing}?key={key}&date={date}&hour={hour}&responseType={type}

Where:

{thing}

A valid thing name.

{key}

Since storage only applies to locked things, you have to specify a key. To find out about locked things, please visit here.

{date}

The calendar date (YYYY-MM-DD) from which you'd like to start your query. The response will be a maximum of one day.

{hour}

The hour of the day represented in the date parameter in 24-hour (00-23) format. If this parameter is included, a maximum of 1 hour will be returned starting at this hour. This paramater is optional. If not included, all dweets for specified day will be returned.

{type}

Current valid parameters for this are 'csv' and 'json'. If this parameter is left blank, all responses default to hapi-json dweet-speak. CSV is only possible for dweets with a static data model. For example, if your dweet parameters are 'temp' and 'humidity' and then change to 'status' and 'speed', the api will respond with an error when trying to output CSV.

An example for getting all the dweets for a thing on Jan 31st between 1-2pm in CSV

https://dweet.io/get/stored/dweets/for/my_thing?key=abc123&date=2016-01-31&hour=13&responseType=csv

Real-time Streams

You can also create a real-time subscription to dweets using a "chunked" HTTP response.

Just make a call to

https://dweet.io/listen/for/dweets/from/my-thing-name
(Note, this won't work in a standard browser)

From a unix command line you can run the following command to see it working:
curl -i https://dweet.io/listen/for/dweets/from/my-thing-name

The server will keep the connection alive and send you dweets as they arrive, like:

{"thing":"my-thing-name","created":"2014-02-17T01:10:21.901Z","content":{"foo":"bar"}}

If you don't know what a chunked HTTP response is, it might be easier to use one of our client libraries below.

Alerts

Alerts notify you when something in the data you dweet falls outside set of conditions. Alerts are reserved for locked things only.

To set an alert, make a call to:

https://dweet.io/alert/{recipients}/when/{thing}/{condition}?key={key}

Where:

{recipients}

A comma separated list of Email addresses. If you want to send a text/SMS message, you can do that too (via Email)— just check this out.

{thing}

A valid thing name.

{condition}

A simple javascript expression to evaluate the data in a dweet and to return whether or not an alert should be sent. You can reference the actual data in the dweet as a javascript object, like dweet.my_field or dweet["my_field"]. If the javascript expression returns anything other than a "falsey" value (false, null, undefined, 0, etc.), an alert will be sent.

For example, alert me when a temperature becomes extreme:

dweet.temp <= 32 || dweet.temp >= 212

You can also create more complex, multi-state alerts by returning a string:

if(dweet.temp <= 32) return "frozen"; else if(dweet.temp >= 212) return "boiling";

Note that the javascript expression you provide for the condition is limited to 2000 characters and may not contain complex things like loops and some other javascript reserved words. However, things like Math functions are supported.

You should normally URL-encode your condition, but you can also pass the condition in the body of a post message if it does not fit within the URL.

{key}

Since alerts are only allowed on locked things, you have to specify a key. To find out about locked things, please visit here.

Putting it all together:

https://dweet.io/alert/me@mydohmain.com/when/my_thing/dweet.donut_qty<=0?key=abc123

To remove an alert, you can call:

https://dweet.io/remove/alert/for/{thing}?key={key}

Client Libraries

You can also access dweet.io even quicker and easier with these pre-built client libraries.

Node.js

https://github.com/buglabs/node-dweetio (Official)

Javascript

https://github.com/buglabs/dweetio-client (Official)

Python

• https://github.com/paddycarey/dweepy (Unofficial)
• https://github.com/bliti/pydweet (Unofficial)

Ruby

https://github.com/vannell/ruby-dweetio (Unofficial)

Lock a thing