Shoudio API v1 *public beta
May 2011
docs revision 1.2
Shoudio The Location Based Audio Platform
Record, Share & Discover audio snippets
in this hidden world of location bound sounds.
api features:
oauth2 (ssl!)
rest
json
API endpoint:
https://shoudio.com/api/v1/{methodname}
API Authentication endpoint:
https://shoudio.com/oauth2/{authorize|token}
Contents:
1. Authentication explained (oAuth2):
To Summarize: Shoudio oAuth2 flow
1. Authentication explained (oAuth2):
(facebookish)
- Register your App for oAuth2 tokens here: (Shoudio account required) You will need to specify a callback url where we send your apps’ users and the access_codes for exchange for long-lived oauth_tokens
- Note your client_id and client_secret. Don’t share them with anyone (especially the secrett)
- Check out the sample below using firefox / chrome ‘Poster’ extension which lets you post
After having setup your app client_id & client_secret in your app (not for public, except the client_id), you can check out this example flow for authentication:
- Redirect the user you want to authenticate it’s Shoudio account away from your site to https://shoudio.com/oauth2/authorize.php?client_id=YOUR_CLIENT_ID&response_type=code&state=true
- The user will either hit ‘sign-in’ and grant your app access or hit ‘cancel’ and deny the request.
- If a user cancels your callback will be called with the following params: ?error=access_denied
- If a user grants your app access to his account he/she will be redirected to your callback url with the following params appended:
?code=b7ad29f8dcb0173ea96d531ae02f61d6
- This temporary access-code will have a very short expiration time.
- Now exchange the access-code for the long-lived oauth2 token by calling (e.g. via cURL) a POST to
https://shoudio.com/oauth2/token
with the following parameters:
grant_type | “authorization_code” (its just that string) |
client_id | your_apps_client_id, which you received upon registering your app at https://shoudio.com/developer/newapp |
client_secret | your_apps_client_secret, which you received upon registering your app at https://shoudio.com/developer/newapp |
redirect_uri | your apps callback url, which you defined upon registering your app. |
code | the short lived access-code we just passed back to you via the callback |
7. Expected the following response if everything went OK:
{"oauth_token":"9c475d030ccd22279af6bd6402f8c253","expires_in":314496000,"scope":null}
Now store that access_token safely, you are responsible for it on behalf of your and our users.
you have to sign calls to the API on behalf of the user’s with their oauth_token by appending it as the oauth_token POST/GET param to every request
8. Or a descriptive error while exchanging the access-code for the oauth_token can occur:
error example 1:
{"error":"invalid_request","error_description":"Invalid grant_type parameter or parameter missing"}
error example 2:
{"error":"expired_token"}
Screenshot ‘Poster Extension’
Example succesfull access-code-to-oauth_token exchange POST (step 6&7 in the process described above):
To Summarize: Shoudio oAuth2 flow
2. Shoudio API core concept
(v1 may 2011 - public beta)
!!!! Public beta: Things can (but shouldnt) break.
API endpoint:
https://shoudio.com/api/v1/{methodname}
(connect over SSL)
Methods:
note: all methods have to be called with authorized oauth_token.
If you need public access check out Sections 3 & 4 about oEmbed and RSS feeds
retrieve data:
/api/v1/user
/api/v1/user-followings
/api/v1/user-followers
/api/v1/geo
/api/v1/channel
/api/v1/place
post a shoudio:
/api/v1/post
API Errors
/api/v1/user
returns userinfo + recent shoudios for given username
https method:
GET
params:
* denotes obligatory param
username | string, 15char max | * |
lat&lon | decimal | optional (will trigger to calculate a distance value being returned based upon (lat,lon) you give. |
max-results | int (default:20, max:50) | optional |
page | int (default:1) | optional |
oauth_token | string 20char | * |
example call:
https://shoudio.com/api/v1/user/erwblo?oauth_token=f95134f71ed352a28ae872e7aa37e65f&username=erwblo&max-results=4&page=1&lat=52.509326&lon=13.434391
example response: (truncated)
{
- status: {
code: "200 OK"
message: "Results for /user"
description: "Yes"
}
- user: {
id: "1"
username: "roelandp"
created_at: "2010-09-13 16:34:37"
updated_at: "2011-05-20 15:27:46"
img_ext: "jpg"
totalshouts: 84
totalfollowers: 37
totalfollowings: 119
ifollow: false
}
+ shoudios: [ … ]
- oauth: {
client_id: "77dd0284d02006a709c5"
expires: "1620871103"
scope: null
userid: "1"
}
}
The shoudios array in the above response contains a list of shoudios (array) structured like:
shoudios: [
- {
id: "1004"
- user: {
avatar: "http://noise.shoudio.com/avatars/100x100/1.jpg"
img_ext: "jpg"
username: "roelandp"
uid: "1"
}
uid: "1"
created_ago: "5 days ago"
created_at: "2011-05-21 19:09:04"
distance: "667.4835346968"
lat: "51.70311737"
lon: "3.74137235"
published: "1"
speed: "-1"
altitude: "0"
heading: "-1"
locationAccuracy: "2499"
altitudeAccuracy: "-1"
locationTimestamp: "1305894821"
placeid: "0"
channelid: "0"
message: "Gestrand"
duration: "68.596"
nearby: "Duinoordweg 6, 4328 Burgh-Haamstede, Netherlands"
hasmp3: "1"
- audio: {
mp3: "http://noise.shoudio.com/mp3/shoudio_1004.mp3"
wav: "http://noise.shoudio.com/wav/shoudio_1004.wav"
}
hasimg: "1"
}
]
/api/v1/user-followings
returns recent shoudios from given username’s people he/she is following
(like twitter’s timeline)
https method:
GET
params:
* denotes obligatory param
username | string, 15char max | * |
lat&lon | decimal | optional (will trigger to calculate a distance value being returned based upon (lat,lon) you give. |
max-results | int (default:20, max:50) | optional |
page | int (default:1) | optional |
oauth_token | string 20char | * |
example call:
https://shoudio.com/api/v1/user-followings?oauth_token=f95134f71ed352a28ae872e7aa37e65&username=roelandp&max-results=4&page=1
example response: (truncated)
/api/v1/user-followers
returns recent shoudios from given username’s people he/she is followed by
(check what people who are interested in you are shouting)
https method:
GET
params:
* denotes obligatory param
username | string, 15char max | * |
lat&lon | decimal | optional (will trigger to calculate a distance value being returned based upon (lat,lon) you give. |
max-results | int (default:20, max:50) | optional |
page | int (default:1) | optional |
oauth_token | string 20char | * |
example call:
https://shoudio.com/api/v1/user-followers?oauth_token=f95134f71ed352a28ae872e7aa37e65&username=roelandp&max-results=4&page=1
example response: (truncated)
/api/v1/geo
returns shoudios nearby given coordinates
(check what people near place lat;lon X are shouting)
https method:
GET
params:
* denotes obligatory param
lat & lon | decimal | * |
oauth_token | string 20char | * |
example call:
example response: (truncated)
/api/v1/channel
returns shoudios from given channel
(a channel is a #hashtag, public group)
https method:
GET
params:
* denotes obligatory param
channel | string | * |
max-results | int (default:20, max:50) | optional |
page | int (default:1) | optional |
oauth_token | string 20char | * |
example call:
https://shoudio.com/api/v1/channel?oauth_token=f95134f71ed352a28ae872e7aa37e65f&channel=sxswnl
example response: (truncated)
/api/v1/place
returns shoudios from a given place
(a place is a dedication location, we currently use foursquare places)
https method:
GET
params:
* denotes obligatory param
place | string (either our id, or a foursquare place id) | * |
max-results | int (default:20, max:50) | optional |
page | int (default:1) | optional |
oauth_token | string 20char | * |
example call:
example response: (truncated)
/api/v1/post
post new shoudio to the user’s timeline
(and additionally, check in on Foursquare, Facebook, Twitter)
- please use sequential uploading (not parallel)
- 1 concurrent request per user
https method:
POST
params:
* denotes obligatory param
Obligatory Core params:
mesage | string (140 char max) Note: you can add 1 #hashtag in the message, it will add this recording to that #hashtag channel (see channels elsewhere in this doc) | * |
lat | decimal | * |
lon | decimal | * |
oauth_token | string (20 char) | * |
Obligatory Files data (audio & image):
audio (any param name will do) | mp3 or wav (max filesize alltogether 80mB) | * |
image (any param name will do) | jpg,jpeg,gif,png (max filesize alltogether 80mB) Use square images, if it is not square, cropping is applied. | optional |
Optional Metadata params:
created_at | int (seconds, unix timestamp) | optional (use when recording time differs from time of upload) |
deviceid | string/int | optional (you can give it so we hexdec the device id (e.g. iPhone UDID) |
Optional GPS metadata params:
speed | int meters per second | optional |
altitude | int meters | optional |
heading | int degrees counting clockwise relative to the true north | optional |
locationAccuracy | int meters, accuracy level of the lat lon | optional |
altitudeAccuracy | int meters, accuracy level of the altitude | optional |
locationTimestamp | int timestamp unix in seconds, last updated time of the gps on the device | optional |
Optional Share/Distribute/checkin params:
postFb ** | boolean | optional |
postTwit ** | boolean | optional |
postFs ** foursquare | boolean | optional |
postSc ** soundcloud | boolean | optional |
fsplaceid a foursquare place id | string | optional, but if used in combination with fsplacename |
fsplacename a foursquare place’s name | string (foursquare place name) | optional, but if used in combination with fsplaceid |
** notes on sharing: setting any of these params to TRUE will cause a crosspost on the given platform. This will only happen if the user has actually given Shoudio permission to crosspost on his behalf on those networks.
If you want to use Sharing, you should always ask the user if they do want a crosspost to take place. In our app for example, we present On/Off switches per social network, which users simply tick to turn the sharing on or off on that particular network.
Additional note on Foursquare:
If you want to check a user in on a given place, provided the user has authorized Foursquare with Shoudio, you have to pass 3 fields: postFs = true, fsplaceid = ‘FSPLACEID’, fsplacename = ‘Barbican Centre’’. This will lead to a checkin with the ‘message’ as comment. If fsplaceid and fsplacename are not given, but postFs is, a regular shout on Foursquare will occur.
example call:
example response: (truncated)
API Errors
If the API errors usually the only response is a json formatted ‘error’ block like this:
{
error: {
code: "403 Unauthorized"
message: "use httpS"
description: "You tried to reach our APIs over regular http traffic, however since we use oAuth2 we only allow SSL connections"
}
}
The errors should be pretty self explanatory, following HTTP codes with additional desciptions about specific errors.
3. oEmbed & Widgets
oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or in our case Interactive playable Audiomaps) when a user posts a link to that resource, without having to parse the resource directly.
you can read the full spec at http://oembed.com
Shoudio widgets and oEmbed
Our oEmbed API endpoint: http://shoudio.com/api/oembed
url schemes for Shoudio are (behind bold text is variable) :
http://shoudio.com/channel/herotrip
http://shoudio.com/user/roelandp
the supported formats aligned with oEmbed spec: json and xml
if you append a callback parameter the json will be turned into jsonp
example call:
http://shoudio.com/api/oembed?url=http://shoud.io/roelandp&format=json
example response:
{
version: "1.0"
provider_name: "Shoudio, the location based audio platform"
provider_url: "http://shoudio.com"
author_name: "Roelandp"
author_url: "http://shoudio.com/user/roelandp"
title: "Roelandp on Shoudio"
type: "rich"
width: 300
height: 454
html: "<iframe src="http://noise.shoudio.com/gadget/map.html?u=roelandp" style="width: 300px; height: 454px; background:transparent;" scrolling="no" marginwidth="0" marginheight="0" frameborder="0" vspace="0" hspace="0" width="300" height="454"></iframe>"
}
4. iTunes podcast & Rss feeds
Public available
Shoudio’s RSS feeds can be consumed by any rss reader and as playlists for e.g. the JW Player. The feeds are optimized to serve as iTunes podcast feeds as well. Simply replacing the http:// for itpc:// causes the feeds to load into iTunes and offers the users to subscribe to the feed as a podcast.
Feed types:
- user
http://shoudio.com/user/roelandp.rss
- channel
http://shoudio.com/channel/herotrip.rss
5. Show us your stuff!
Made something cool on Shoudio’s APIs? Or have some questions?
Share with us on:
- Twitter: http://twitter.com/Shoudio
- Facebook: http://facebook.com/Shoudio
cheers,
Team Shoudio
Amsterdam, NL