stumble!to

API Reference

About the API

Stumble!to offers a simple HTTP-based API.

Request parameters are encoded using the standard application/x-www-form-urlencoded format. All responses are JSON.

API Key and Signing

All requests must include api_key and signature parameters. API keys are linked to a single venue, so the first thing you’ll need to do is create one.

Add Venue

All requests must be signed using your secret key. Signatures are calculated by urlencoding all parameters sorted by name and computing an HMAC-SHA512 hash. The result is then appended to the query as signature in hexdigest format.

Sample Code

The easiest way to understand the API is to look at example code. The following examples are currently available:

Dnsmasq DHCP Agent - Submits MAC addresses from dnsmasq’s DHCP server.
Shoe Agent - Uses a Nike+ iPod receiver to detect shoe sensors. See also the Nike+ How-To Guide.

The following two agents are using a deprecated API and will be updated soon. Both of these scripts are intended to be run out of cron on your router:

DHCP Agent - Reads MAC addresses from the DHCP leases table.
ARP Agent - Reads MAC addresses from the ARP table.

Methods

POST /api/update

Currently there is a single API method called update. Simply submit a list of nearby devices and stumble!to will check-in any matching users.

Parameters

api_key - See above.
signature - See above.
devices - JSON-encoded array of devices, in the following format:
```
[
  { 'identifier': 'ab-12-cd-34', 'type': 'shoe' },
  ...
]
```

Result

A JSON dict containing the following keys:

status - See above.
devices - The same list of devices you POSTed with an additional result field.
```
[
  { 'identifier': 'ab-12-cd-34', 'type': 'shoe', 'result': 'success' },
  ...
]
```
Possible result codes:
- success - User was checked-into one or more social network.
- skipped - Device was found, but no checkins were made. This usually means that the user is already checked in.
- notfound - Device was not found.

Example Request

In this example, we are using an API key of 11111111111111111111111111111111 and an API secret of 22222222222222222222222222222222.

api_key=11111111111111111111111111111111&devices=%5B%7B%22identifier%22%3A+%22ab-12-cd-34%22%2C+%22type%22%3A+%22shoe%22%7D%5D&signature=008cd8443143a82c98427c1bca033f019745380cc33b300bfe682577d0a217c960dfa2fc03ccf0031ebc972abdcf141b030987429bebce607ae21386ab63e228

Example Response

{
  'success': true,
  'devices': [
    { 'identifier': 'ab-12-cd-34', 'type': 'shoe', 'result': 'success' }
  ]
}