API for livestreams
Updated over a week ago

Artists and their teams can display live streaming events with specific call to action buttons.

How to identify a live stream event

When you call Bandsintown’s Event API to get your events, the key is to identify when the event is a Live Stream. One way to identify it is using the field ‘type’ from the venue we are returning. In this case, all our live streams will have:

"type": "Virtual"

Others fields you will need are the event ‘timezone’ and ‘date time’:

"timezone": "America/Los_Angeles"
"datetime": "2020-04-17T19:00:00"

The venue will be included with the following fields:

  • ‘name’ field as ‘Streaming LIVE’

  • ‘type’ field as ‘Virtual’

  • ‘timezone’ as a standard string format (i.e ‘America/New_York’. The other venue fields are empty.

  • ‘title’ field will be replacing the venue ‘place’, if provided

Follow these 4 steps for live stream events

The following examples are created in javascript.

1. Identify when your event is virtual.

const isVirtualEvent = ({ venue }) => venue.type && venue.type === "Virtual";
const isVirtual = isVirtualEvent(event)

2. Identify the time zone of the person who is accessing your website to determine if your show is about to start or not.

npm i date-fns date-fns-timezone
import { parseFromTimeZone } from 'date-fns-timezone'; import differenceInMinutes from 'date-fns/difference_in_minutes';
export const isLive = eventData => { const { datetime, venue } = eventData; const { timezone } = venue; if (!timezone) { return false; } if (!datetime) { return false; } const eventUtcTime = parseFromTimeZone(datetime, { timeZone: timezone } ); const delta = differenceInMinutes(eventUtcTime, new Date()); // between 15 mins before start and 4 hours after start; return delta <= 15 && delta >= -(60 * 4)}

3. The key to giving the best experience to your fans is to show the right button at the right time. For example:

WATCH LIVE call to action button is displayed 15 minutes before the live stream starts and will remain visible 4 hours after the start time. When an event is streaming, it will have an offer with type ‘Watch Live’, which will replace the ‘Tickets’ one. The url for that offer will redirect to the stream url set in Bandsintown for Artists platform. If there are tickets and a streaming url, both urls are included in a dropdown list. Click destination is the url provided in the field “offer” on our API response

Example:

"offers": [ {"type": "Watch Live", "url": "https://www.bandsintown.com/l/102218931?app_id=js_example &came_from=267&utm_medium=api&utm_source=public_api &utm_campaign=watch_live", "status": "available" }

NOTIFY ME call to action button is displayed as soon as your live streaming event is available to be published. Please note that it is required to be published a minimum of 4 hours before the show.

Click destination is the event url with the query params:

trigger=notify_me and utm_campaign=notify_me_livestream

4. If the event is a live stream and therefore has a virtual venue:

  • Don’t display location information (City, Region, Country)

  • Artists can choose if they want to show the Event Title or the words "Streaming LIVE"

  • To set this on your website, you will need to verify the information on the event field "Title".

If the event field "Title" is empty, then you can show the information on the venue field "Name".

Screen Shot 2020-05-06 at 1.56.13 PM.png

If the event field "Title" is not empty, then you can show information returned on the Title.

Screen Shot 2020-05-06 at 1.56.53 PM.png
  • Include the date and timezone after the venue name (i.e. “Streaming LIVE @ 7:00pm EST”). The timezone needs to be converted from the full text to the abbreviation “America/New_York” => “EST”.

Did this answer your question?