GET ​/api​/v3​/station​/:id

Returns a station by ID.

Request

Example Request

{
  "genres": "Rock,Blues",
  "genres_excluded": "Country",
  "from_date": 20150820,
  "to_date": 20150820,
  "auth_token": "abc1245920feab98ca",
  "sort": "all"
}

Example Parameters

  • genres: Only include gigs by bands matching any of these genres. Multiple genres should be separated by a single comma. When genres and genres_excluded are not provided, it is fetched from current account/guest's preferences.

    • Required: no
    • Type: string
    • Example: Rock,Blues
  • genres_excluded: Omit any gigs by artists with any of these genres. Excluded genres take precedence over included genres. For instance, if you've included Rock but excluded Metal, a band that is tagged with both genres will not be included in the station.

    • Required: no
    • Type: string
    • Example: Country
  • from_date: Date in format YYYYmmdd, to begin date range from

    • Required: no
    • Type: string
    • Example: 20150820
  • to_date: Date in format YYYYmmdd, to end date range at

    • Required: no
    • Type: string
    • Example: 20150820
  • auth_token: The user's auth_token obtained by calling the auth API.

    • Required: no
    • Type: string
    • Example: abc1245920feab98ca
  • sort: Supported only for venue, event, and local stations. Supported options are upcoming, popular, top_voted and all. upcoming returns tracks from bands with shows upcoming first. popular returns an optimized playlist. top_voted returns in descending order of upvotes. all pulls a track per artist in a round robin fashion.

    • Required: no
    • Type: string
    • Example: all

Response

Example Response

{
  "meta": {
    "page": 1,
    "total_pages": 10,
    "per_page": 20,
    "records": 200,
    "sort": "all",
    "sort_options": [

    ]
  },
  "station": {
    "title": "Starry Plough Radio",
    "id": 123,
    "station_type": "Venue",
    "banner_url": "http://example.com/banner.jpg",
    "timed_callouts": [
      {
        "id": 5,
        "title": "Starry Plough Radio",
        "duration": "01:49",
        "media": {
          "audio": {
            "url": "http://deliradio.com/assets/starry_plough.m4a",
            "hq_url": "http://deliradio.com/assets/starry_plough.mp3"
          }
        },
        "intervals": [
          {
          },
          {
          }
        ]
      }
    ],
    "playlist": [
      {
        "track": {
          "id": 3,
          "album_id": 12,
          "artist_id": 2,
          "title": "Shine on you Crazy Diamond",
          "duration": "03:18",
          "single": true,
          "you_follow": true,
          "media": {
            "audio": {
              "url": "https://example.com/4/20/mobile_05_Pajaros_Sin_Alas.m4a",
              "hq_url": "https://example.com/4/20/mobile_05_Pajaros_Sin_Alas.mp3"
            }
          }
        }
      }
    ],
    "artists": [
      {
        "id": 2,
        "band_profile_id": 1,
        "name": "The Howling Bees",
        "location": "Houston, TX, US",
        "genres": [
          {
          }
        ],
        "slug": "the-howling-bees",
        "twitter_handle": "@howlingbees",
        "you_follow": true,
        "shows": [
          {
            "id": 84211,
            "venue_id": 7680,
            "artist_id": 8570,
            "show_time": {
            },
            "you_follow": true,
            "ticket_url": "http://deliradio.com/go?bid=123&bn=The+Classic+Crime&url=http%3A%2F%2Fwww.bandsintown.com%2Fevent%2F7402810%2Fbuy_tickets%3Fartist%3DCrime",
            "photo_landscape_100": "https://deliradio-development.s3.amazonaws.com/uploads/picture/band/14278/68151/landscape_100_38bd769c-3d83-42ff-a66f-4e69ae71f18a.jpg"
          }
        ],
        "media": {
          "photos": [
            {
            }
          ]
        }
      }
    ],
    "albums": [
      {
        "id": 12,
        "name": "Greatest Hits",
        "image_url": "https://deliradio.s3.amazonaws.com/artwork/4/image.jpg"
      }
    ],
    "venues": [
      {
        "id": 100754,
        "name": "EastDown Warehouse",
        "capacity": 100,
        "city": "Houston, TX, US",
        "description": "Featuring Magnifi",
        "lat": "29.7630556",
        "lng": "-95.3831",
        "slug": "palladium-radio",
        "twitter_username": "@brooklynbowl",
        "official_station_id": 123
      }
    ]
  }
}

Response Parameters

  • meta: Contains paging information about the response

    • Required: no
    • page: The page number (starting at 1)
      • Required: no
      • Type: integer
      • Example: 1
    • total_pages: The total number of pages you can request.
      • Required: no
      • Type: integer
      • Example: 10
    • per_page: The number of records returned in each page.
      • Required: no
      • Type: integer
      • Example: 20
    • records: The total number of records available.
      • Required: no
      • Type: integer
      • Example: 200
    • sort: Describes the sort order of the playlist.
      • Required: yes
      • Type:
        • null
        • string
      • Example: all
    • sort_options: An array of the supported sort options for this station.
      • Required: yes
      • Type:
        • null
        • array
      • Example: [

]

  • station: A wrapper object that represents the station.

    • Required: yes
    • title: The title of the station. Should be displayed when playing the station.
      • Required: yes
      • Type: string
      • Example: Starry Plough Radio
    • id: The unique identifier for the station.
      • Required: yes
      • Type:
        • number
        • string
      • Example: 123
    • station_type: The type of station returned. Also used to record statistics.
      • Required: yes
      • Type: string
      • Example: Venue
    • banner_url: The banner image url to display for the station (if it has one).
      • Required: no
      • Type:
        • string
        • null
      • Example: http://example.com/banner.jpg
    • timed_callouts: Callouts that should be interleaved within the playlist based on the interval.

      • Required: yes
      • Type: array
      • Items

        • Required: no
        • id: The id of the callout.
          • Required: yes
          • Type: integer
          • Example: 5
        • title: The title of the callout.
          • Required: yes
          • Type:
            • null
            • string
          • Example: Starry Plough Radio
        • duration: The duration of the callout.
          • Required: yes
          • Type:
            • null
            • string
          • Example: 01:49
        • media:

          • Required: yes
          • __audio__:

        • intervals: An array of intervals that determines the duration between callout plays. The first item represents the duration before the initial callout. If the value is 0, the callout is played prior to any playlist items. The second item represents the duration between all subsequent audio callouts.

          • Required: yes
          • Type: array
          • Items The number of minutes
    • playlist: A list of ordered, playable items. These are generally tracks, but might include other items such as audio_inserts. Consumers must tolerate additional types of playlist items that it does not process and exclude those items in their processing.

      • Required: yes
      • Type: array
      • Items

        • Required: yes
        • track: A song by a band. This is the most common, and central part, of any playlist response.

          • Required: yes
          • id: The track id
          • album_id: The id of the album. Can be used to lookup in top-level albums key.
          • artist_id: The id of the artist. Can be used to lookup in a top-level bands key.
          • title: The title of the track.
          • duration: The duration of the track. In minutes:seconds format.
          • single: Indicates if the track is one of the band's singles.
          • you_follow: Indicates if the track is followed/favorited by the current account.
          • __media__: Includes various media elements for the playlist item.

    • artists: A lookup of the artists represented in the playlist.

      • Required: no
      • Type: array
      • Items

        • Required: no
        • id: the id of the artist
          • Required: yes
          • Type: integer
          • Example: 2
        • bandprofileid: the id of the band_profile
          • Required: yes
          • Type: integer
          • Example: 1
        • name: the name of the band
          • Required: yes
          • Type: string
          • Example: The Howling Bees
        • location: The band's home town.
          • Required: yes
          • Type: string
          • Example: Houston, TX, US
        • genres: A list of genres for the band.

          • Required: yes
          • Type: array
          • Items

        • slug: Used when creating URLs

          • Required: yes
          • Type: string
          • Example: the-howling-bees
        • twitter_handle: The twitter handle.

          • Required: yes
          • Type:
            • null
            • string
          • Example: @howlingbees
        • you_follow: Indicates whether the current user follows this artist.

          • Required: yes
          • Type: boolean
          • Example: true
        • shows: A list of upcoming shows for this artist.

          • Required: yes
          • Type: array
          • Items

        • media: A container for any media related to the band.

          • Required: yes
          • __photos__: A list of photos uploaded by the band.

    • albums: A list of albums represented by tracks in the playlist.

      • Required: no
      • Type: array
      • Items

        • Required: no
        • id: The album id.
          • Required: yes
          • Type: integer
          • Example: 12
        • name: The name of the album.
          • Required: yes
          • Type: string
          • Example: Greatest Hits
        • image_url: An image for the album
          • Required: yes
          • Type: string
          • Example: https://deliradio.s3.amazonaws.com/artwork/4/image.jpg
    • venues: A lookup of venues referenced in the shows collection

      • Required: yes
      • Type: array
      • Items

        • Required: no
        • id: the id of the venue
          • Required: no
          • Type: integer
          • Example: 100754
        • name: the name of the venue
          • Required: no
          • Type: string
          • Example: EastDown Warehouse
        • capacity: Capacity of venue
          • Required: yes
          • Type: integer
          • Example: 100
        • city: the city string of the venue
          • Required: no
          • Type: string
          • Example: Houston, TX, US
        • description: description of venue
          • Required: no
          • Type:
            • null
            • string
          • Example: Featuring Magnifi
        • lat: the latitude of the venue
          • Required: no
          • Type: string
          • Example: 29.7630556
        • lng: the longitude of the venue
          • Required: no
          • Type: string
          • Example: -95.3831
        • slug: The unique slug for a venue.
          • Required: no
          • Type:
            • null
            • string
          • Example: palladium-radio
        • twitter_username: Twitter handle name of the venue
          • Required: no
          • Type:
            • null
            • string
          • Example: @brooklynbowl
        • officialstationid: The ID for the official station for this venue
          • Required: yes
          • Type:
            • null
            • integer
          • Example: 123

Response Codes

Successful Response Codes

  • 200: The station response was successful.

Failure Response Codes

  • 400: One or more of the required parameters were missing or incorrect.

  • 404: The venue was not found.