SERMONAUDIO WEB SERVICES Available services: - saweb_get_sermons.aspx - Get list of sermons - saweb_get_speakers.aspx - Get list of speakers - saweb_get_languages.aspx - Get list of languages - saweb_get_eventtypes.aspx - Get event types To use our web services, first retrieve your broadcaster API key from the Members Only Area on the SermonAudio web site. This key will be passed as a parameter to all of our web services. To activate your API key, go to www.sermonaudio.com and log in to the Members Only section, and the Personal tab. You will see a section for API Key, and can enable your key. Once you do, the key will appear in a gray box. All of our web services return JSON as their output. Almost all current scripting and programming languages have support for JSON. When an error condition occurs, all the web services return a one-item JSON dictionary with "error" as the only key: { "error": "message text" } After calling our web services, the first action that client code should take is to check for the key "error" in the JSON return. Our web services should work with either GET or POST parameters. ---------------------------------------------------------------------- GET SERMONS FOR SOURCE You can page through a list of your sermons with this web service. Only sermons posted by your broadcaster account are avilable via your API key. Two other parameters are required: The page size (number of items per page) and the specific page requested. URL: https://www.sermonaudio.com/api/saweb_get_sermons.aspx?apikey=&page=1&pagesize=10 This web service returns an array of dictionaries, one dictionary per sermon, such as this sample: [ { "rownum": "1", "sermonid": "1303234343", "title": "The Sin of Unbelief", "subtitle": "", "date": "10/20/1996 11:00:00 AM", "speaker": "Rev. Ian Goligher", "eventtype": "Sunday - AM", "bibletext": "Isaiah 7:1-16" } , {...} ] The list has the newest sermons first, in descending order. You can also get the total number of rows with page=total, which returns a one-item JSON dictionary: { "total": "785" } Note: Page size is currently limited to a maximum of 100. Any page size over this number will act as if it is 100 when paging. This restriction reduces load on our server. For this web service to complete successfully, the API key must be valid. If the key is missing or invalid, the usual "error" one-item dictionary is returned. Also, the API key must be for a FULL Member, otherwise an error is returned. Only a FULL Member publishes sermons. Also, the optional combination of category and item parameters may be given to limit the output which is returned, such as in this example: https://www.sermonaudio.com/api/saweb_get_sermons.aspx?apikey=&page=1&pagesize=10&category=series&item=New%20Testament%20Christianity Category may have the values: "speaker", "eventtype", "series", "year". Speaker and series are free-format text fields. Speaker must match one of the speakers returned by the get speakers API call. Event type must match one of the event types returned by the get event type API call. Year must be an integer. Be sure to check the return value for the "error" value if using category/item. A text description of any problem encountered will be returned in this field. The page=total parameter when used with category/item will reflect the total number of items after the category/item filtering has been applied. ---------------------------------------------------------------------- GET LIST OF SPEAKERS You may retrieve a list of speakers for your broadcaster account using this web service, which can be used (for example) to populate a drop-down box. Note that while you can create new speakers via the SermonAudio web site, our web service only lists existing speakers. URL: https://sermonaudio.com/api/saweb_get_speakers.aspx?apikey= Returns a JSON array of all speakers for the current source (which comes from the API key): [ "Dr. Alan Cairns" , ... "Mr. Chris Killen" ] The list is sorted starting with the speakers with the most sermons in descending order to the speakers with the fewest. For this web service to complete successfully, the API key must be valid. If the key is missing or invalid, the usual "error" one-item dictionary is returned. Also, the API key must be for a FULL Member, otherwise an error is returned. Only a full member has a speaker list. ---------------------------------------------------------------------- GET LIST OF LANGUAGES You can retrieve a list of languages which our web site allows using this web service, such as (for example) to populate a drop-down box. URL: https://sermonaudio.com/api/saweb_get_languages.aspx?apikey= Returns a JSON array of all languages: [ "Afrikaans" , ... "Zulu" ] For this API to return successfully, the API key must be valid. If the key is missing or invalid, the usual "error" one-item dictionary is returned. Note: English does not appear in the list because it is the default language. ---------------------------------------------------------------------- GET EVENT TYPES You can retrieve a list of event types which our web site allows using this web service, such as (for example) to populate a drop-down box. URL: https://sermonaudio.com/api/saweb_get_eventtypes.aspx?apikey= Returns a JSON array of all languages: [ "Audio Book" , ... "Youth" ] For this API to return successfully, the API key must be valid. If the key is missing or invalid, the usual "error" one-item dictionary is returned. ----------------------------------------------------------------------