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=<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=<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=<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=<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=<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.

----------------------------------------------------------------------