|
ReferenceIndex
Index page for the API Reference Material
API Reference
Things to know / rememberThis is a work in progress and meant as a hint to start playing with the API. If you can guess what an API does then by all means give it a go! The API is REST-based. All requests follow a standard format, see the api introduction for an overview of how to perform these requests. All parts of a URL in bold are parameters that should be replaced before making calls! Any /account/... urls will act on the user corresponding to the OAuth access token provided. They will return an unauthorized response if OAuth authentication hasn't been performed. Audio ClipsAll audio clipsThese return paginated responses.
returns all boos in chronological order (most recent first) returns the editorially "featured" boos as appear on the web-site returns the most popular audio clips ordered by recent listens Tagged audio clipsThis call will return a paginated response.
returns all the audio clips tagged with the specified tag. The tag in the URL should be normalised.
User's audio clipsThese calls will return paginated responses.
returns the audio clips uploaded by the user specified by user_id.
returns the audio clips uploaded by username. If known, using the user's id is preferred, since it's guaranteed to never change.
returns the audio_clips uploaded by the user linked to the OAuth access token used. User's followed clipsThese calls will return paginated responses.
returns the audio clips uploaded by users followed by the user specified by user_id.
returns the audio clips uploaded by users followed by the user linked to the OAuth access token used. Clips by locationFiltering for clips with locationThere is a feed of boos restricted only to those with a public location, which may be useful for generating maps of boos, etc. This can be accessed using a call to the URL:
At the moment it doesn't follow the same rules regarding context (i.e. /users/12/audio_clips/located.json won't return user 12's located clips - this is a major FIXME for me...) Search by distance from pointIf you want to get a list of boos increasing near a specific long/lat point you can call this:
The results will be ordered by a combination of how recent they are and how far away from the point they are, so something 20m away done 2 days ago could be after something 100m away done 1 hour ago. There isn't currently a way to manipulate this behaviour. Comments welcomed/appreciated but unfortunately not enough time to act on them in the near future. Search for boos "nearby"You can search for clips nearby another clip:
Which will return clips in the same order as clips returned from a long/lat point. For this and the clips from point call you'll also get a "bearing" and "distance" tag in the returned XML for each result which will tell you the bearing and distance of each result from the query location, using the haversine approximation. Don't know if that is useful, but it's there! Clips within a bounding boxYou can request all the clips that fall within an arbitrary bounding box.
Pagination rules apply, so it's possible to retrieve all clips inside the box... Google Earth KML FeedJust "for fun" there is a KML generator which you can plug in to google earth. Absolutely unsupported and will potentially break in the future :-) Add a "network link" in google earth to this url And you'll get the push-pins / audioboo icons on the map. You can even specify the view based refresh and google earth will automatically load clips from the viewport as you move around the map. If you use: Then it will produce a KML with a tour of the most recent clips. Audio clip details
returns the details of the audio clip specified by audio_clip_id.
this will respond with a browser re-direct to the mp3 audio data for the audio clip specified by audio_clip_id Posting audio clipsPOST /account/audio_clips.format this will post an audio clip into the recent clips of the user linked to the OAuth access token used. To post to a channel, you can use POST /channels/channel_id/audio_clips.format which will post an audio clip to the specified channel. The same parameters are used for either endpoint:
The uploaded audio data as a multipart file, see ReferenceIndex#Audio_Formats and ReferenceIndex#File_Uploads.
A universally unique identifier, to aid the server in duplicate-detection. The uuid must not contain spaces or a newline characters.
The uploaded image data as a multipart file, see see ReferenceIndex#Image_Formats and ReferenceIndex#File_Uploads.
The title for the audio clip.
The time that the clip was recorded, in "YYYY-MM-DD HH:MM:SS ±HHMM" format.
The tags to associate with the audio clip. These should be comma separated, and use quotes if the tag itself contains a comma.
Boolean value indicating if location should be public on the website. Use strings 'true' or 'false'. If public_location is true, the server expects these values to also be completed:
The latitude value of the location, encoded as a string representation of a decimal number between -90.0 (south) to +90.0 (north).
The longitude value of the location, encoded as a string representation of a decimal number between -180.0 (westwards) and 180.0 (eastwards).
The accuracy of the reading, in meters - omit this value if it's not available. Image FormatsOnly JPEG and PNG image formats are tested and known to work at the point. Audio FormatsWe will attempt to transcode any audio file that you throw at us. We explicitly support FLAC, MP3, and AIFF/WAV. File UploadsFiles should be sent using HTTP multipart encoding. You must include a 'filename' parameter in the Content-Disposition multipart header, to ensure that our webserver processes it as a file. If you're authenticating via OAuth, be sure to use the Body Hash extension. Updating audio clipsYou can update audio clips by sending a PUT request to the boo's location : PUT /audio_clips/audio_clip_id.format It accepts the same parameters as those shown in the creation method. Deleting audio clipsYou can mark audio clips for deletion by sending a DELETE request to the boo's location : DELETE /audio_clips/audio_clip_id.format UsersLists of Users
this call requires exactly one of two parameters to find a specific user. The behavior if both parameters are supplied is undefined. find[username]=*username* will return at most one user who has the specified user exactly. This is the recommended way to find an id for a named user. find[query]=*query* will perform a more flexible search for the query against the users on the system. It can return multiple users that match the query and you can use the * as a wildcard User details
This will return the details for the user specified by the user_id parameter.
This will return the details of the user linked to the OAuth access token. Listing followers / following usersJust to clarify: Followers = users who have chosen to follow a user Followings = users who a specific user is following
You can specify a find[user_id] parameter to limit the results to a particular set of users. To, for example, find out if stephen fry is following you, you'd call: GET /account/followers.format?find[user_id]=11 You can supply multiple, comma-separated id's to restrict to a series of users, to find if any of the AudioBoo team are following you, try: GET /account/followers.format?find[user_id]=12,17,5,30,16 Creating and Deleting followings
Both of these calls require a single parameter following_user_id which is the id of the user to follow or un-follow. MessagingAll of these calls require an authenticated user. InboxThe messages in the user's inbox. Paginated and in chronological order (most recent first)
Message details
returns the details of the message specified by message_id. Post messageThis will send a message to another user (from the authenticated user).
The following parameters are identical to posting an audio clip:
The following parameters are unique to posting a message:
The user ID of the recipient.
If a reply, the ID of the message it is in reply to. BlockingSome users may be blocked from messaging others. If you GET the details of an individual user, there is a messaging_enabled flag indicating whether that user can be messaged. Each message in the inbox contains a user[messaging_enabled] flag showing if that message can be replied to. | |
► Sign in to add a comment
To clarify - a "user_id" is a number, and not your screen name (if you wondered why it doesn't work). If a user_id is not valid, you get a 404 page not found error.
If you're wondering what your own user_id is, you'll find it by going to http://audioboo.fm/profile and holding your mouse over the iTunes or RSS feed buttons - you'll see your user_id as the number in the link.
Cheers for the clarification! I know I desperately need to clean this reference up...
You can also call
and it will always return a single user back
Creating and Deleting followings Creating works fine, no problems, but DELETE doson`t work, message: you are not authorizied
Jens
To search an audio clip like the function on upper right conner main page. You can also call
it will return clips with "hello" in its title or tag.
Hello,
Some questions about audio post:
POST /account/audio_clips.xml
1) What multipart encoding are you using? (e.g. multipart/form-data) 2) How are you signing the body, do you include an 'Oauth_body_hash'? Thanks Steven
Can't you offer an end point to get a user's clips using its username and not its user_id? Otherwise we need to do two calls (a first one to turn the username to a user id then only fetch the clips). Something like http://api.audioboo.fm/audio_clips.json?find[username]=$USERNAME Thanks so much!
@wangkaiou that does not seem to work with jsonp. Having such endpoint would be very helpful though.
@xdam We could add it, but would be interested in what your use case is. Wherever we provide a username, we also provide a user id.
codecs faq: 3gpp, amr-nb
will your uploads support this codec?
Details: for VOICE content recorded on smart phones, the main codec is amr-nb, 8000Hz , 1 channel which resolves to a bandwidth requirement of about 12K on wireless networks. If you assume that phones and their recorder apps will be used to produce content, then the MIME type of the local file on the phone is 'audio/amr' and the file type is '.3gpp'. The phone is not really the place to do transcoding, so the option is to support the transcode on your servers. Do you?
That should be fine. If in doubt, you could try uploading them manually at http://audioboo.fm/boos/new to check what happens.