JSON API

This app features an API to allow other sites, mainly those in the Amazing family, to query the schedule and recording archive. The API is intended to be called from JavaScript and so responds in JSON.

Note Some API calls will only be allowed if they originate from a whitelist of acceptable sites. These are intended for use in-house only.

Site Identifier

All requests accept the following means of specifying the site (UK / US) a request has come from. Set to uk or us to enable appropriate filtering of shows, setting of airing_schedule, etc.

GET Parameter: siteid
Header: X-Site-Identifier

This is exactly the same as the amazingtunes V2 API accepts, for consistency.

Shows

The {showname} identifier is used to identify a show. It should be the same identifier as used for the show on amazingradio.com.

/shows.json

Lists all the shows visible on amazingradio.com

Parameters

takeover - set to true or false to show only Takeover shows, or non-takeove shows respectively.
order - defaults to 'alpha' for A-Z ordering. Set to newest to order by date created or updated to order by date last modified.
uuids - optional string of comma-separated UUIDs to restrict the output to

[
  {
    "id": "chill",
    "name": "Amazing Chill",
    "slug": "A chilled description",
    "plain_slug": "A chilled description",
    "url": "http://amazingradio.com/shows/chill",
    "presenter": "DJ Fear",
    "social_accounts": {
      "facebook": "amazingradio",
      "twitter": "amazingradio",
      "instagram": "amazingradio",
      "email": "info@amazing.media"
    },
    "takeover": false,
    "airing_schedule": "weekdays 3-7pm",
    "homepage_image": "https://amazingradio-assets.s3.amazonaws.com/2015/10/13/11/55/06/23b75263-e7d5-40fa-a15f-7de1e13ddfe1/Bethan_onair.jpg",
    "homepage_image_wide": null,
    "thumbnail_image": "https://amazingradio-assets.s3.amazonaws.com/2015/10/13/11/55/06/19197f39-d0f0-4fa5-a4ba-bddac9ef555c/bethan_small.jpg",
    "square_300_image": null,
    "created_at": "2017-03-15T11:12:09"
  },
  //...
]

/shows/{showname}.json

Information regarding the show identified by {showname}.

{
  "name": "Afternoons with James",
  "presenter": "DJ James",
  "social_accounts": {
    "facebook": "dj.james",
    "twitter": "dj_james",
    "instagram": "djjames01",
    "email": "dj.james@amazing.media"
  },
  "url": "http://amazingradio.com/shows/dj-james",
  "slug": "New music from <strong>DJ James</strong>",
  "plain_slug": "New music from DJ James",
  "homepage_image": "http://amazingradio-assets.s3.amazonaws.com/2012/12/07/16/39/21/308/djjames_onair.jpg",
  "thumbnail_image": "http://amazingradio-assets.s3.amazonaws.com/2012/12/07/16/39/21/589/djjames_small.jpg",
  "rewind": [
    {
      "s3_url": "http://s3.amazonaws.com/amazingrewind/rewind-43_1354621729.mp3",
      "broadcast_from": "2012-10-26T17:33:00Z",
      "broadcast_to": "2012-10-26T18:33:00Z",
    },
    {
      "s3_url": "http://s3.amazonaws.com/amazingrewind/rewind-39_1354620707.mp3",
      "broadcast_from": "2012-10-26T17:33:00Z",
      "broadcast_to": "2012-10-26T21:33:00Z",
      "slug": "An evening special with live coverage from the Power Metal Extravaganza taking place in Newcastle"
      "plain_slug": "An evening special with live coverage from the Power Metal Extravaganza taking place in Newcastle"
    }
  ]
}

/shows/{showname}/airings.json

Lists each broadcast of a given show, most recent first, without repeats. Each 'airing' has its own rewind_url for its Rewind.

Parameters

only_rewinds - if true, only returns broadcasts with a rewind that is ready to stream
page - page number (defaults to 1)

{
  "airings": [
    {
      "id": 147,
      "start_time": "2020-05-15T11:00:00.000Z",
      "end_time": "2020-05-15T13:00:00.000Z",
      "duration_in_min": 120,
      "slug": "Your heart will skip a beat when this one drops - coming soon to a database near you.",
      "presenter": "Bobby Drop-tables",
      "repeat": false,
      "rewind_url": null,
      "presenter_covering": false,
      "homepage_image_wide": "https://amazingradio-assets.s3.amazonaws.com/image.png",
      "square_300_image": "https://amazingradio-assets.s3.amazonaws.com/image2.png"
    },
    //...
  },
  "meta": {
    "page": 1,
    "total_pages": 3,
    "per_page": 20,
    "total_entries": 58
  }
}

/shows/{showname}/airings/{id}.json

Displays a single broadcast for a given show

{
  "id": 147,
  "start_time": "2020-05-15T11:00:00.000Z",
  "end_time": "2020-05-15T13:00:00.000Z",
  "duration_in_min": 120,
  "slug": "A special takeover. Your heart will skip a beat when this one drops - coming soon to a database near you.",
  "presenter": "Bobby Drop-tables",
  "repeat": false,
  "rewind_url": "https://aws.amazon.com/amazingrewind/rewind1.mp3",
  "presenter_covering": false,
  "homepage_image_wide": "https://amazingradio-assets.s3.amazonaws.com/image2.png",
  "square_300_image": "https://amazingradio-assets.s3.amazonaws.com/image4.png",
  "show": {
    "id": "beatsshow",
    "name": "Beats Show",
    "slug": "Dropping that beat, every Friday from 7pm",
    "plain_slug": "Dropping that beat, every Friday from 7pm",
    "url": "https://amazingradio.com/shows/beatsshow",
    "presenter": "Mr Beat",
    "social_accounts": {
      "facebook": null,
      "twitter": "jamesds89",
      "instagram": "jamesds89",
      "email": "james.shepherd@amazing-media.com"
    },
    "takeover": false,
    "airing_schedule": null,
    "created_at": "2015-09-10T14:30:12.000Z",
    "homepage_image": "https://amazingradio-assets.s3.amazonaws.com/image1.png",
    "homepage_image_wide": "https://amazingradio-assets.s3.amazonaws.com/image2.png",
    "thumbnail_image": "https://amazingradio-assets.s3.amazonaws.com/image3.png",
    "square_300_image": "https://amazingradio-assets.s3.amazonaws.com/image4.png",
    "listen_again_image": "https://amazingradio-assets.s3.amazonaws.com/image5.png"
  }
}

/shows/{showname}/rewind.json

Lists the archive of recordings made for every broadcast of a show.

Parameters

limit - limit the number of recordings returned (defaults to 10)

[
  {
    "s3_url": "http://s3.amazonaws.com/amazingrewind/rewind-1_1352480579.mp3",
    "broadcast_from": "2012-11-03T08:00:00Z",
    "broadcast_to": "2012-11-03T10:00:00Z",
    "slug": "A Guy Fawkes Saturday morning special awaits - tune in to find out!"
  }
]

Channels

The {channel} identifier is used to identify a channel. Currently we use uk for our main UK channel.

/channels/{channel}/onair.json

Parameters

offset - number of minutes to offset the result by. Use this to find out what was airing at a given time in the past.


{
  "show": {
    "name": "Afternoons with James",
    "presenter": "DJ James",
    "social_accounts": {
      "facebook": "dj.james",
      "twitter": "dj_james",
      "instagram": "djjames01",
      "email": "dj.james@amazing.media"
    },
    "url": "http://amazingradio.com/shows/dj-james",
    "slug": "New music from <strong>DJ James</strong>",
    "plain_slug": "New music from DJ James",
    "homepage_image": "http://amazingradio-assets.s3.amazonaws.com/2012/12/07/16/39/21/308/djjames_onair.jpg",
    "thumbnail_image": "http://amazingradio-assets.s3.amazonaws.com/2012/12/07/16/39/21/589/djjames_small.jpg",
  },
  "start_time": "2012-12-11T19:00:00Z",
  "end_time": "2012-12-13T07:00:00Z"
}

/channels/{channel}/week_ahead.json

Returns all the shows airing throughout the next 7 days, including today.

Parameters

us_only - set to true to only show the US shows in the shedule.

/channels/{channel}/upcoming.json

Parameters

limit - number of upcoming shows to return.

Returns a list of the upcoming radio shows on the specified channel, in the order they will be broadcast.

Coming soon...

Add the following API calls:

/channel/{channel}/weekly.json - provide week parameter to get all broadcasts that week
/channel/{channel}/daily.json - provide date parameter to get all broadcasts that day
/channel/{channel}.json - details about a channel, i.e. timezone, location, description