Data Standardization across the DC Music Scene
You would not be able to see shows on our app without some kind of data regularity on venue websites. In other words, the only reason we're able to grab show info is that it's being displayed in a list, and in a programmatically predictable way.
There are 3 ways/methods we can grab data:
- From a publicly accessible API.
- From predictable HTML markup.
- From JSON Structured Data.
We wanted to put together this reference guide to help music venues and event promoters get their show data on our app. While creating instructions on how to build a publicly accessible API is out of scope for this data standardization endeavor, we wanted to go over methods 2 and 3.
If your venue's shows are already on the app, we still encourage you or your developer to take a look at this guide. There may be some data points for your shows that are not being (fully) included.
DC Music Live Show Data
Before we get started, you should know that we look for and collect certain data points for every show:
- ID - required field
- Event Title - required field
- Event Title 2 (eg. Supporting Acts)
- Description
- Status (eg. Canceled, Postponed, or Sold Out)
- Age Restriction (eg. 18+ or All Ages)
- Virtual (whether the event is or is not accessible via online link)
- Date - required field
- Time
- Price
- Event Link - required field ( ideally a link to the event itself, but the venue page can be used in a pinch )
- Ticket Link
- Image Link
This is our list for now, though we'd be open to coordinating the collection and display on our app of additional properties. (Think having "ticket count" as properties we could all agree to collect and display).
Method 2: How to Provide Predictable HTML Markup
There are 3 key pieces to know when providing predictable HTML markup for ease of data grabbing.
- Provide all event data on one page
- Provide as many data points as you can
- Each data point must be inside its tag
A code visual:
<!DOCTYPE html>
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>DATA SAMPLE</title>
</head>
<!--
REQUIRED FIELDS:
data-dcm-id,
data-dcm-title,
data-dcm-date,
data-dcm-eventLink,
-->
<body>
<div
data-dcm
data-dcm-id="UNIQUE-RANDOM-STRING"
data-dcm-title="HEADLINER NAME"
data-dcm-title2="SUPPORT ACTS"
data-dcm-description="Watch this incredible band perform live at our venue this fall!"
data-dcm-genre="Jazz"
data-dcm-status="Canceled"
data-dcm-date="07/27/2022"
data-dcm-time="7:00 PM"
data-dcm-price="$20.50"
data-dcm-age-restriction="18+"
data-dcm-virtual="true"
data-dcm-eventLink="https://venue.com/band"
data-dcm-ticketLink="https://ticket.com/event"
data-dcm-imgSrc="https://image.api.com/id"
style="display: none;"
/>
</body>
</html>
In this example, our sample venue has 1 event in a single HTML div
tag. This satisfies key 1: Provide all event data on one page.
The first property is simply data-dcm
. Having this allows us to predictably grab all div
s with this property.
The rest of the properties (data-dcm-*
) provide all the data points we need, satisfying key 2: Provide as many data points as you can. You only need to provide us with the 4 required properties we mentioned earlier, but more information will both enrich the user experience for our community and help inform them of event details.
To satisfy key 3, each data point corresponds to one data-dcm-*
property. We are not lumping the date and time together, for instance.
If you look at each div, none of them have content inside of them. They are purely there to hold data and don't display anything on your screen. We've added a "display: none;"
CSS property to drive that idea home, though it's not necessary.
What if you want to provide this data alongside your regular markup?
Everyone's situation may be different. Let's talk -- schedule a meeting with us / reach out to our email: hello@dcmusic.live
Why do you require a unique string identifier?
In the case of all methods, we are asking that you assign each of your events a unique ID. This can be a number, it can be letters, it can be whatever you like and generated however you like. The point of this is to better track changes on a single event. For example, if a show's Status and the show's Event Title change, we can more easily track that change for that particular event.
Method 3: How to provide JSON Structured Data
You may have heard the term Structured Data before when it comes to SEO. Structured Data is a markup language (like how HTML is markup language) that communicates content in an organized manner. This allows search engines like google to display your content in an organized way. On our end, we use it to grab show data to display on our app.
Typically, the format of structured data is based on a Schema.org type. In our case, we can parse certain properties of the Event / MusicEvent type. You'll notice there are a lot of properties you can provide, but the ones we support are:
- name
- description
- startDate
- offers.price or offers.lowPrice
- url
- offers.url
- image
- eventStatus
- genre (unofficial)
- dcmID (unofficial)
This will make more sense if you look at an actual example. Here are two events, in a script tag on Mr. Henry's calendar page:
<script type="application/ld+json">
[
{
"@context": "http://schema.org",
"@type": "Event",
"name": "Capitol Hill Jazz Jam",
"description": "<p>The Capitol Hill Jazz Jam (CHJJ) is a weekly jazz jam session held at Mr. Henry’s Restaurant in the Capitol Hill neighborhood of Washington D.C. every Wednesday from 8-11 PM. The jam session, formed in February 2015 by saxophonist Herb Scott operates every week and has hosted instrumentalists, vocalists, tap dancers, poets, and[...]</p>\\n",
"image": "https://www.mrhenrysdc.com/wp-content/uploads/2018/11/CHJJ.jpg",
"url": "https://www.mrhenrysdc.com/event/capitol-hill-jazz-jam/2022-03-02/",
"startDate": "2022-03-02T20:00:00+00:00",
"endDate": "2022-03-02T23:00:00+00:00",
"performer": "Organization"
},
{
"@context": "http://schema.org",
"@type": "Event",
"name": "Pablo Regis",
"description": "<p>Pablos Regis is a cavaco player and percussionist performing Brazilian music in the DC metro area. He grew up in Los Angeles and Brasília, surrounded by Brazilian music and culture. Over the years, he has worked with numerous Brazilian musicians and organized events and concerts to bring Brazilian music United[...]</p>\\n",
"image": "https://www.mrhenrysdc.com/wp-content/uploads/2020/01/Pablo-Regis.jpg",
"url": "https://www.mrhenrysdc.com/event/pablo-regis/2022-03-03/",
"startDate": "2022-03-03T19:30:00-05:00",
"endDate": "2022-03-03T22:30:00-05:00",
"offers": {
"@type": "Offer",
"price": "15",
"priceCurrency": "$",
"url": "https://www.mrhenrysdc.com/event/pablo-regis/2022-03-03/",
"category": "primary",
"availability": "inStock",
"validFrom": "2020-01-24T00:00:00+00:00"
},
"performer": "Organization"
}
]
</script>
Here, Mr. Henry's has all of the required properties we are looking for. There are a few things they could improve on:
- Include eventStatus and genre
- Specify a price for their first event. If they wish to have the "FREE" label added to this event in our app, they would need to specify a price of 0.
- Specify the full description instead of truncating it. To have the full description be present in the app, it would need to be included here.
When writing your structured data, there can be specific values you'll need to provide, such as for EventStatus, but overall, the rest of the data just comes from you.
Wrap Up
We hope this reference guide provides the information you need to effectively disseminate your show data for our data retrieval.
You may find that one method may be more accessible than the other for you/your team. Either way, we're here to support this effort. Please reach out to us once you've implemented these changes or if you need help along the way. We can be reached at the following email: hello@dcmusic.live