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:
Just replace my-thing-name with a unique name. That's it!
Any query parameters you add to the request will be added as key-value pairs to the content of the dweet. For example: https://openxc.dweet.io/dweet/for/my-thing-name?hello=world&foo=bar
You can also send any valid JSON data in the body of the request with a
Dweet.io will also respond to JSONP requests with a
?callback= query parameter.
While we recommend using a secure https:// connection, dweet.io also supports un-secure http://
connections for devices that don't support SSL.
Dweet.io will respond with:
To read the latest dweet for a thing, you can call...
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...
Dweet.io will respond with one or more dweets which look like:
"this": "is cool!"
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 are free for Ford users. .
To get all of a thing's dweets for a given hour:
A valid thing name.
Since storage only applies to locked things, you have to specify a key.
The calendar date (YYYY-MM-DD) from which you'd like to start your query. The response will be a maximum of one day.
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.
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
Yes, you can create a real-time subscription to dweets using a "chunked" HTTP response.
Just make a call to:
(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://openxc.dweet.io/listen/for/dweets/from/my-thing-name
The server will keep the connection alive and send you dweets as they arrive, like:
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:
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
A valid thing name.
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";
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.
Since alerts are only allowed on locked things, you have to specify a key.
Putting it all together:
To remove an alert, you can call:
In contrast to our original API set (now known as our Public APIs), data and assets using the Pro APIs benefit from expanded security and access control. As such, you will need to include a token in the header of every Pro API request. We created two types of tokens - the 'Thing Token' and 'Master Token' - with different access control capabilities. Depending on the type of token provided in the request, API access may be further limited by the role of the user - Admin, Manager, or Viewer - that is making the request.
The new (/v2) APIs, which provide enhanced security, management, configuration, storage, and alerting functionality suitable for production-ready development. These APIs can only be used with your OpenXC DweetPro account. You must have a valid Ford email to register.
Our original, free and “ridiculously simple” API set. Use these APIs to get started working with dweet.io - no signups, no hassle. Data sent through these APIs will appear on our publically accessible https://openxc.dweet.io/see
(The X-DWEET-AUTH header)
In order to use the Pro APIs, you will need to include the header “X-DWEET-AUTH” in every request, with an encoded alphanumeric string value which we call a Token. This allows owners of a Pro account to manage access to the data and the control functionality of the assets associated with their account. In order to provide enhanced security and access control, we created two types of Tokens - the Master Token and Thing Token - which are used in different contexts depending on who or what is making the API call.
Master Token (Session Token)
The Master Token is a user-level, session-based token made up of approximately 265 alphanumeric characters. Typically used for administrative functionality (which can also be accomplished in the OpenXC.dweet Management UI).
- Can provide access to all Pro APIs depending on the user's account type
- Authorization to use different subsets of the Pro APIs is determined by the role of user:
- Admins: Full access
- Managers: Access to MOST APIs, except billing, lock purchasing, and org/account/user creation
- Viewers: limited to read-only fuctionality for Things, Collections and Dweets
- Retrieved by issuing a
POST /v2/users/login with a username field and password field in the request body.
- NOTE: After logging in to the Management Portal, clicking on the Console page will show only the APIs available to that user.
Thing Token (Device Token)
The Thing Token is a static, restricted, account-wide token, made up of approximately 150 alphanumeric characters. A physical device is best suited to use the Thing Token.
- Used for basic communication to/from OpenXC-dweet.
- Limited to the following API requests:
The purpose of the Thing Token is to enable assets that are interested in data messaging APIs - not management functionality - to be able to continuously communicate with the platform. As such, this Token does not expire unless intentionally re-generated by an Admin user (as may be necessary in a situation where the Thing Token is compromised to unauthorized parties).
Re-generating the Thing Token can be accomplished either through the management UI (in the Organization tab of the Account page), or by issuing a GET /v2/accounts/token (HINT: this request is made with the X-DWEET-AUTH header set to the Master Token of a logged-in Admin).
Proceed with caution: Re-generating the Thing Token will de-authorize the previous Thing Token and all previously locked Things.
Another term for locking a Thing. Provisioned/locked Things can take advantage of long term storage, alerts, and can be organized within a Collection.
- A Lock is used to provision a Thing. After applying a Lock to a Thing, data storage and alerting features are enabled for that Thing, as well as the ability to add that Thing to a Collection.
- Locks can be purchased and added to an account by Admin users only. Managers can then manage the association of the available Locks to different Things, either by locking unprovisioned things or unlocking already-provisioned things.
- Each Lock has three unique characteristics: Lock ID, Master Key and Read Key.
- To get a new lock, go to the Locks page (You must be signed in to the Management Portal). Next, Select Buy Lock Enter coupon: openxcdweetv2
- You will be given a new lock. Toggle the Used/Unused button to see the new lock credentials.
After locking a Thing, any requests to the /dweets APIs using a Thing Token must also include one of the lock’s Keys as described below.
When a Thing Token is provided in the request header, the Lock’s Master Key can access all Thing Token enabled APIs (POST /v2/dweets, GET /v2/dweets/latest, GET /v2/dweets). This key is typically used to allow an asset to send data to the platform.
When a Thing Token is provided in the request header, the Lock’s Read Key can access only the Thing Token APIs that retrieve data of a thing (GET /v2/dweets/latest, GET /v2/dweets, GET /v2/dweets/listen). Sharing the Read Key along with the Thing Token allows users to provide read-only access of their Things’ latest data to others.
A Collection is a group of locked Things, used for organizational purposes. When locking/provisioning a Thing, it must be added to a Collection. Unlocked/unprovisioned things are held in a special Collection called “UNPROVISIONED”.
Creating a new Thing inside of a specific Collection will auto-assign that new Thing an Unused Lock. You can unlock a Thing, or Move a Thing from one Collection to another.
Labels can be used to group Things together that may be in different Collections, since a Thing can only be in one Collection at a time. You can add labels to your Thing, then GET Things by Label. The API also returns the total number of Things with the specific label. This could be useful for grouping items together in various ways, and seeing alerts for Things by group.
OpenXC Application and VI
You can also access dweet.io even quicker and easier with the OpenXC Enabler Application. Use this smartphone app to connect a VI device, add a tracefile, or record your phone sensors.