Overview
The OpenMedia API is a web service complement to our lightweight, browse-oriented OPML interface. It is a collaborative specification pioneered by Sonos, Inc. and adapted to radio by RadioTime. It officially launched in October 2008 and supports hundreds of thousands of connected devices across the globe.
OpenMedia is a traditional document-oriented web service. This means it has a WSDL endpoint (http://opml.radiotime.com/Radio.asmx?WSDL) and uses SOAP syntax and semantics.
The basic units of currency in the API are the MediaCollection and MediaMetadata. These translate to menus (i.e., navigable categories) and items (stations, shows and recent topics/podcasts), respectively. The entirety of the service offering consists of 5 methods:
- getMetadata – Retrieve lists of menus and items
- getMediaMetadata – Retrieve information about a specific item
- getMediaURI – Retrieve a stream URL for an item
- search – Find a specific item by text query
- reportStatus – Provide playability status to the service
While most of the data required for each service call will be found in the SOAP envelope, there are three important HTTP headers that also influence behavior:
- Accept-Language – When set to a value other than en-US, the service will parse and potentially localize content. Currently supported locales are es-ES/es-MX (Spanish), de-DE (German), it-IT (Italian), sv-SV (Swedish), fr-FR (French), and nl-NL (Dutch).
- X-Forwarded-For – The service typically uses the originating IP address to determine local radio options and restrictions/availability. If your implementation proxies requests on your customer’s behalf, this header may be used to pass through the original address.
- Accept-Encoding – When set to gzip/deflate, the service will send compressed responses.
Integration Considerations
As an API designed for a variety of media types, OpenMedia specifies a number of elements and fields not applicable to a traditional radio data service. These may be safely ignored.
Like OPML, the XML returned by the service may change over time. We will not remove elements or attributes, but we may add them as circumstances warrant.