The Realtime API is a socket connection which displays what's currently happening on your station.

Connection

To connect to the Realtime API you need to initialise a socket on realtime.radiomanager.io:5000 and send authentication data within 5 seconds of the initial connection.

Authentication

For the connection to the Realtime API, you need to have a API key with at least permission to read on Items and Broadcasts. To do this, send a JSON object with type "authentication" and your API Key after the server asks for authentication.

The server will acknowledge it is ready for authentication by:

{"system":{"type":"info","message":"please authenticate using your API key"}}

Then send your key in the following format:

{"type":"authentication","stationData":{"api-key":"YOUR_API_KEY_HERE"}}

The server will respond on correct authentication:

{"system":{"type":"info","message":"authenticated"}}

After authentication the server will send information about the Station, Broadcast and current Item. And subsequently sends data on the Broadcast and Item if anything changes.

Responses

Using the socket, you can get some basic information about the current items happening on the station. A response contains Stationdata, Broadcastdata and Itemdata. The responses are in JSON.

Station data

Stationdata contains information about the station you are subscribed to. For example, station "Plux Static" would return the following information:

{
   station:{
      id:1,
      name:'Plux Static Fm',
      created_at:'2017-06-13T09:32:39+02:00',
      updated_at:'2017-07-25T16:36:20+02:00',
      short_name:'Plux Fm',
      medium_name:'Plux Static',
      website:'pluxbox.com',
      logo_square:'http://i.imgur.com/jAUv8yy.jpg?1',
      email:'info@pluxbox.com',
      keywords:false,
      description:'Plux Static brings you your favourite hits!',
      sms:'0031357606060',
      telephone:'0031357606060',
      genre_id:3571,
      language:'Dutch',
      active:true,
      logo_rectangle:'http://i.imgur.com/jAUv8yy.jpg?1',
      logo_128x128:'http://i.imgur.com/jAUv8yy.jpg?1',
      logo_320x240:'http://i.imgur.com/jAUv8yy.jpg?1',
      logo_600x600:'http://i.imgur.com/jAUv8yy.jpg?1',
      pay_off:null,
      pty_code:10,
      pty_type:'rds',
      station_key:'XxXxXxXxX'
   }
}

Broadcast data

Broadcastdata contains data about your current broadcast. For broadcast "Live Broadcast" the data returned would be:

{
   broadcast:{
      id:927,
      program_id:278,
      model_type_id:6,
      station_id:null,
      field_values:{
         image:null
      },
      title:'Live Broadcast',
      start:'2017-08-03T00:00:00+02:00',
      stop:'2017-08-04T00:00:00+02:00',
      created_at:'2017-08-03T09:27:18+02:00',
      updated_at:'2017-08-03T09:27:18+02:00',
      genre_id:null,
      description:'Live Broadcast on your station',
      short_name:'Live',
      medium_name:'Live Broadcast',
      website:'livebroadcast.com',
      email:'admin@livebroadcast.com',
      recommended:null,
      deleted_at:null,
      language:'English',
      published:true,
      repetition_uid:null,
      repetition_type:'1 week',
      repetition_end:null,
      repetition_start:null,
      repetition_days:null,
      pty_code_id:null
   }
}

Item data

Itemdata is the data of the item currently playing in your broadcast. The song item in your current broadcast with artist "DJ Midnight" and title "Looking at the stars" will return the follwing:

{
   status:'playing',
   block_id:9542,
   model_type_id:14,
   order:3,
   updated_at:'2017-08-03T09:29:55+02:00',
   created_at:'2017-08-03T09:29:55+02:00',
   id:647,
   field_values:{
      artist:'DJ Midnight',
      title:'Looking at the stars'
   },
   external_id:1501745395,
   start:'2017-08-03T09:29:55+02:00',
   duration:60,
   title:'Looking at the stars',
   import:true,
   model_type:{
      id:14,
      name:'Song',
      model:'item',
      created_at:'2017-06-13T09:32:45+02:00',
      updated_at:'2017-07-07T15:02:00+02:00',
      options:{
         color:'#4ebed4',
         talk:false,
         hidden:false
      },
      order:1,
      deleted_at:null
   },
   block:{
      id:9542,
      broadcast_id:927,
      start:'2017-08-03T09:00:00+02:00',
      stop:'2017-08-03T10:00:00+02:00',
      created_at:'2017-08-03T09:27:19+02:00',
      updated_at:'2017-08-03T09:27:19+02:00',
      deleted_at:null,
      broadcast:{
         id:927,
         program_id:278,
         model_type_id:6,
         station_id:null,
         field_values:{
            image:null
         },
         title:'Live Broadcast',
         start:'2017-08-03T00:00:00+02:00',
         stop:'2017-08-04T00:00:00+02:00',
         created_at:'2017-08-03T09:27:18+02:00',
         updated_at:'2017-08-03T09:27:18+02:00',
         genre_id:null,
         description:'Live Broadcast on your station',
         short_name:'Live',
         medium_name:'Live Broadcast',
         website:'livebroadcast.com',
         email:'admin@livebroadcast.com',
         recommended:null,
         deleted_at:null,
         language:'English',
         published:true,
         repetition_uid:null,
         repetition_type:'1 week',
         repetition_end:null,
         repetition_start:null,
         repetition_days:null,
         pty_code_id:null
      }
   },
   tags:[

   ],
   contacts:[

   ]
}

Errors

The service might return errors on input. These are system messages of the type "error". A few common examples:

Will be send when the user inputs invalid JSON:

{"system":{"type":"error","message":"no valid JSON"}}

Will be send when authentication times out:

{"system":{"type":"error","message":"authentication timed out (no authentication data send)"}}

Will be send when authentication fails:

{"system":{"type":"error","message":"wrong key"}}