Skip to content

Instantly share code, notes, and snippets.

@caseywreed

caseywreed/bandsintown-api-anlaysis.md

Last active April 6, 2019 02:34
Show Gist options
  • Save caseywreed/6e3f58e1f9c1d7363a15e91f6a5bc5fd to your computer and use it in GitHub Desktop.
Save caseywreed/6e3f58e1f9c1d7363a15e91f6a5bc5fd to your computer and use it in GitHub Desktop.
Download ZIP
Bandsintown API Breakdown
Raw
bandsintown-api-anlaysis.md

Summary

Some issues have arisen concerning data consistency and availability within the Bandsintown API V3. Specifically, the name field on the VenueData model does not always accurately supply the name of the Venue associated with an Event. Furthermore, detailed data used to render BIT pages is excluded from payloads returned by the API. For this analysis, we'll ignore how this data is used in the Artist Growth system and instead focus on how the Bandsintown API supplies data.

Issues Noted

  • venue.name is replaced by an Event's title in BIT VenueData model payloads whenever a title is present for an Event. Thus, an Event with values for both properties will never supply the value of both properties.
  • Relevant data used to render Bandsintown Event pages is not present in data returned from the API
  • The latitude and longitude coordinates returned by the API do not map to a Venue's location

Artifacts

Let's take a look at the some of the data artifacts in-play. These will include JSON payloads sent via the Bandsintown API as well as examples of source data and screenshots from Bandsintown pages themselves.

Raw Payload Sent to Artist Growth via BIT API V3

This payload (truncated for clarity) is an example of data returned from the Bandsintown API and can be replicated with the supplied curl command. This data will cover both of the event examples provided below.

$ curl --verbose "https://rest.bandsintown.com/artists/kimberlydunn/events/?format=json&app_id=ag&api_version=3.0"
> GET /artists/kimberlydunn/events/?format=json&app_id=ag&api_version=3.0 HTTP/1.1
> Host: rest.bandsintown.com
> User-Agent: curl/7.64.0
> Accept: */*
-----------------------------------------------------------------------------------------------------------------------
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 6396
< Connection: keep-alive
< Date: Thu, 04 Apr 2019 20:27:53 GMT
< x-amzn-RequestId: 1f8f306f-5718-11e9-b009-0da4743339e0
< Access-Control-Allow-Origin: *
< x-amz-apigw-id: XoVPbFo4IAMFQKg=
< X-Amzn-Trace-Id: Root=1-5ca668c9-93eec1c15b123a4c99ecb408;Sampled=0
< X-Cache: Miss from cloudfront
< Via: 1.1 19270b9ebeb1c54b61c028475c86d6dd.cloudfront.net (CloudFront)
< X-Amz-Cf-Id: kgqxfYY6aBUMcOmnbN8G-8cTa71L2qbasXtMM9tVMmgS9i1hAa4h3g==
<
[
  ...
  {
    "artist_id": "1321673",
    "datetime": "2019-05-25T12:00:00",
    "description": "",
    "id": "100826327",
    "lineup": [
      "Kimberly Dunn"
    ],
    "offers": [
      {
        "status": "available",
        "type": "Tickets",
        "url": "https://www.bandsintown.com/t/100826327?app_id=ag&came_from=267&utm_medium=api&utm_source=public_api&utm_campaign=ticket"
      }
    ],
    "on_sale_datetime": "2019-02-15T10:00:00",
    "url": "https://www.bandsintown.com/e/100826327?app_id=ag&came_from=267&utm_medium=api&utm_source=public_api&utm_campaign=event",
    "venue": {
      "city": "Austin",
      "country": "United States",
      "latitude": "30.2944269",
      "longitude": "-97.6222665",
      "name": "Lone Star Jam",
      "region": "TX"
    }
  },
  ...
  {
    "offers": [
      {
        "type": "Tickets",
        "url": "https:\/\/www.bandsintown.com\/t\/100826270?app_id=artistgrowth-dev&came_from=267&utm_medium=api&utm_source=public_api&utm_campaign=ticket",
        "status": "available"
      }
    ],
    "venue": {
      "name": "Reverb Lounge",
      "country": "United States",
      "region": "NE",
      "city": "Omaha",
      "latitude": "41.29547350000001",
      "longitude": "-95.99383390000001"
    },
    "datetime": "2019-05-16T19:00:00",
    "on_sale_datetime": "2019-03-15T10:00:09",
    "description": "",
    "lineup": [
      "Kimberly Dunn"
    ],
    "id": "100826270",
    "artist_id": "1321673",
    "url": "https:\/\/www.bandsintown.com\/e\/100826270?app_id=artistgrowth-dev&came_from=267&utm_medium=api&utm_source=public_api&utm_campaign=event"
  }
]

Associated Event Source Data

Kimberly Dunn - May 25, 2019

Kimberly Dunn - Lone Star Jam

# An example of the eventInfo object in the page's source data 
# included via window.__data
# Some non-pertitent data (RSVPs, image URLs, etc..) has been excluded
{
  "eventTitle": "Lone Star Jam",
  "dateText": "Saturday, May 25th, 2019",
  "startTimeText": "12:00 PM",
  "venue": {
    "name": "Rodeo Austin",
    "address": "9100 Decker Lake Rd, Austin, TX 78724",
    "url": null
  },
  ...
  "description": {
    "text": null
  }
}

# JSON data included via <script> tags
# Some of this data is repeated or reformatted throughout 
# the page source, so this is just one example
# The DESCRIPTION field has been truncated for brevity
{
  "@context": "http://schema.org",
  "@type": "MusicEvent",
  "name": "Kimberly Dunn",
  "startDate": "2019-05-25T12:00:00",
  "endDate": "2019-05-25",
  "url": "https://www.bandsintown.com/e/100826327-kimberly-dunn-at-rodeo-austin?came_from=244",
  "location": {
    "@type": "Place",
    "name": "Rodeo Austin",
    "address": {
      "@type": "PostalAddress",
      "addressCountry": "United States",
      "addressRegion": "TX",
      "addressLocality": "Austin",
      "streetAddress": "9100 Decker Lake Rd",
      "postalCode": "78724"
    },
    "geo": {
      "@type": "GeoCoordinates",
      "latitude": 30.2944269,
      "longitude": -97.6222665
    }
  },
  "performer": {
    "@context": "http://schema.org",
    "@type": "MusicGroup",
    "name": "Kimberly Dunn",
    "location": {
      "@type": "Place",
      "name": "Austin, TX"
    },
    "genre": "Country",
    "sameAs": "https://www.bandsintown.com/a/1321673-kimberly-dunn?came_from=244",
    "description": "..."
  },
  "description": "Kimberly Dunn at Rodeo Austin 2019-05-25T12:00:00",
  "image": "https://photos.bandsintown.com/thumb/8903783.jpeg"
}
Kimberly Dunn - May 16, 2019

Kimberly Dunn - Reverb Lounge

# An example of the eventInfo object in the page's source data 
# included via window.__data
# Some non-pertitent data (RSVPs, image URLs, etc..) has been excluded
{
  "eventTitle": null,
  "dateText": "Thursday, May 16th, 2019",
  "startTimeText": "7:00 PM",
  "venue": {
    "name": "Reverb Lounge",
    "address": "6121 Military Ave, Omaha, NE 68104",
    "url": null
  },
  ...
  "description": {
    "text": null
  },
}}

# JSON data included via <script> tags
# Some of this data is repeated or reformatted throughout 
# the page source, so this is just one example
# The DESCRIPTION field has been truncated for brevity
{
  "@context": "http://schema.org",
  "@type": "MusicEvent",
  "name": "Kimberly Dunn",
  "startDate": "2019-05-16T19:00:00",
  "endDate": "2019-05-16",
  "url": "https://www.bandsintown.com/e/100826270-kimberly-dunn-at-reverb-lounge?came_from=244",
  "location": {
    "@type": "Place",
    "name": "Reverb Lounge",
    "address": {
      "@type": "PostalAddress",
      "addressCountry": "United States",
      "addressRegion": "NE",
      "addressLocality": "Omaha",
      "streetAddress": "6121 Military Ave",
      "postalCode": "68104"
    },
    "geo": {
      "@type": "GeoCoordinates",
      "latitude": 41.29547350000001,
      "longitude": -95.99383390000001
    }
  },
  "performer": {
    "@context": "http://schema.org",
    "@type": "MusicGroup",
    "name": "Kimberly Dunn",
    "location": {
      "@type": "Place",
      "name": "Austin, TX"
    },
    "genre": "Country",
    "sameAs": "https://www.bandsintown.com/a/1321673-kimberly-dunn?came_from=244",
    "description": "..."
  },
  "description": "Kimberly Dunn at Reverb Lounge 2019-05-16T19:00:00",
  "image": "https://photos.bandsintown.com/thumb/8903783.jpeg"
}

Analysis

Missing or Incorrect Venue Data

As seen in the Lone Star Jam example, if a title is provided for an Event in Bandsintown, it is included as eventInfo.eventTitle in the page source. The name of the associated venue, Rodeo Austin, is included in the source as eventInfo.venue.name and then used to build formatted display strings such as the description value present in the @context data object. Let's take a look at the VenueData object that the Bandsintown API returns for this event, as shown previously in the API response object.

"venue": {
  "city": "Austin",
  "country": "United States",
  "latitude": "30.2944269",
  "longitude": "-97.6222665",
  "name": "Lone Star Jam",
  "region": "TX"
}

In the source data, "Lone Star Jam" is never used in the context of a Venue or Location, but it appears as the value returned by the API instead of the value in the source's eventInfo.venue.name. The actual name of the venue is not present at all in the API data. This results in a situation where the value of VenueData.venue.name is not null and is not the name of the venue

Now let's look at the VenueData returned for an event without a title, the Reverb Lounge example:

"venue": {
  "name": "Reverb Lounge",
  "country": "United States",
  "region": "NE",
  "city": "Omaha",
  "latitude": "41.29547350000001",
  "longitude": "-95.99383390000001"
},

When the value of eventInfo.eventTitle in the page source is null, the Bandsintown API correctly associates the source value, eventInfo.venue.name, as the value returned by the API in the VenueData object.

Data Present in the Page Source and Missing from the API

Here is a list of pertinent location data that is never returned by the Bandsintown API but is included in the page source:

address
streetAddress
postalCode

Latitude and Longitude Values

In the screenshots below, the blue pin represents the Google Maps location for Reverb Lounge or Rodeo Austin while the red pin represents the latitude/longitude coordinates returned by the Bandsintown API. Reverb Lounge plus coords

Rodeo Austin plus coords

In the absence of a name or address, a Bandsintown API consumer might use latitude and longitude to search for and confirm a venue, but that query would provide incorrect results as well.

Conclusions

To ensure that the Bandsintown API can be used thoroughly and correctly by your consumers, a combination of the following solutions could be implemented:

  • Remove the API logic that replaces VenueData.venue.name with an event's title and create a new nullable property on the VenueData model for the value of eventInfo.eventTitle.
  • Augment the VenueData API model to include relevant location data present in the page source, specifically the address, streetAddress, and postalCode properties.
  • Review and correct how the API retrieves latitude / longitude coordinates for locations.
  • Somehow provide API consumers with a more detailed VenueData endpoint. This might consist of providing access to an internal Bandsintown API or creating a new public endpoint with all relevant data.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment