The Sayroom API

Once you've registered your application, it's easy to start requesting data from Sayroom. We provide APIs for accessing sayroom audio messages left by users, or Say's. There are several ways that you can access Say's through our API. This is the common way, where API users simply access our live feed:

Live Feed

http://api.sayroom.com/v1/says/feed?api_key=CLIENT_ID

We currently support the following parameters with all API calls:

  • api_key: Your unique API key given to you when you registered your application

  • n: The number of Says that you want to output in your API call

These are optional parameters that can be passed to the API, depending on which endpoint you use:

  • o: Offset at which to start returning items, default is 0

  • t: Use this when you are looking to only receive Says pertaining to a specific topic or Hashtag

  • u: When you only want Says posted by a specific user, the username should be inputed with this parameter (required when using the "user" endpoint)

  • t: When you only want Says related to a specific topic, the topic should be inputed with this parameter (required when using the "topic" endpoint)

  • f: The format returned by API; the default is json, and the alternative is xml

  • Note: The "missing_image_url" field returned provides a fallback url for the cases in which third party channels fail to return a valid image

Sample return from API:


  {
    "missing_image_url": MISSING IMAGE LOCATION, 
    "offset": THE OFFSET IN WHICH TO BEGIN RETURNING POSTS,
    "limit": THE LIMIT ON RESULTS, CURRENTLY IS 25,
    "total": THE TOTAL AMOUNT OF SAYS IN TOTAL,
    "found": THE TOTAL NUMBER OF SAYS RETURNED,
    "result":
        [{
           "sayid":"UNIQUE ID # FOR THE SAY",
           "url":"URL LOCATION TO STREAM THE SAY",
           "pic":"URL LOCATION FOR IMAGE THE USER IS RESPONDING TO",
           "text":"THE TEXT THAT BELONGS TO THE SAY, NOT THE TRANSCRIPTION",
           "speaker":"THE UNIQUE ID FOR THE SPEAKER OF THE SAY",
           "avatar":"THE URL LOCATION FOR THE USERS AVATAR",
           "fullname":"THE USERS FULL NAME, IE: JOHN DOE",
           "place":"THE PLACE (USER GENERATED), WHERE THE USER IS LOCATED",
           "username":"THE UNIQUE USERNAME FOR THE SPEAKER"
        }],
    "status": STATUS CODE RETURNED, IDEAL IS "ok",
    "error": ERROR CODE RETURNED, IF APPLICABLE,
    "message": MESSAGE RETURNED, IF APPLICABLE }
  }
 

By Topic

Searching by topic is useful when the API developer is looking to mine for the says that are pertaining to a topic of their choice. You could search for all Says that are about Barack Obama, or about the Miami Heat. All spaces should be encoded by a '%20', and also use other URL encoded codes for use. All Says are strictly searched for by tags associated. Here is the URL endpoint:

http://api.sayroom.com/v1/says/topic?api_key=CLIENT_ID&t=TOPIC&n=NUMBER

By Username

Using the API to access a specific users own feed is useful for many reasons. Primarily we find users like to showcase their own Says on their websites, blogs, and other means of expression. Also, if you want to take advantage of using another users audio stream, this can be done using this endpoint. We are developing widgets for users to make this more simple.

http://api.sayroom.com/v1/says/user?api_key=CLIENT_ID&u=USERNAME&n=NUMBER

Android & iOS SDK

iOS

This is our SDK for iOS devices.

Github - SDK

Demo

Android

This is our SDK for android devices.

Github - SDK

Demo

This is currently Version 1 of the Sayroom API, and the development staff is constantly thinking up more data to be utilized through the interface. We would love to see what type of applications our community of developers conjure up. We are also very open to new ideas for future version of the API. If you have any questions, suggestions, or would like to show what you have built, please speak to us on the Sayroom API Forum or email us at api@sayroom.com. Happy coding! - SR Staff