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):

Screenshot ‘Poster Extension’

To Summarize: Shoudio oAuth2 flow

2. Shoudio API core concept

Methods:

/api/v1/user

/api/v1/user-followings

/api/v1/user-followers

/api/v1/geo

/api/v1/channel

/api/v1/place

/api/v1/post

API Errors

3. oEmbed & Widgets

4. iTunes podcast & Rss feeds

5. Show us your stuff!

1. Authentication explained (oAuth2):

(facebookish)

  1. 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
  2. Note your client_id and client_secret. Don’t share them with anyone (especially the secrett)
  3. 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:

  1. 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
  2. The user will either hit ‘sign-in’ and grant your app access or hit ‘cancel’ and deny the request.
  3. If a user cancels your callback will be called with the following params: ?error=access_denied
  4. 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

  1. This temporary access-code will have a very short expiration time.
  2. 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:

https://shoudio.com/api/v1/geo?oauth_token=f95134f71ed352a28ae872e7aa37e6&lat=52.509326&lon=13.434391

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:

https://shoudio.com/api/v1/place?oauth_token=f95134f71ed352a28ae872e7aa37e65f&place=4ccc1ad654f0b1f71bc813ca

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 **

facebook

boolean

optional

postTwit **

twitter

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/-/754

 http://shoud.io/754

 http://shoud.io/username

 http://shoudio.com/channel/herotrip

 http://shoudio.com/user/roelandp

 http://shoudio.com/place/23

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