Pages

Friday, 10 July 2015

Event Markup: Official Venue Sites

Google shows venues' event schedules to millions of users each day in Google Search, Google Maps, and other products. With your venue's calendar displayed on Google, people can easily see event details and find where to buy tickets. To be eligible for these features and to ensure that Google has the right data, you must provide up-to-date event schedules using structured data markup on your official website. This document describes how.
For a 10-minute video tutorial on how Google uses event markup, please see: https://www.youtube.com/watch?v=XXw8g-FbemI 

Providing event data on venue sites

Google’s new approach to organizing event data depends on finding complete event information on each venue’s official website. Human-readable event listings are not sufficient; instead, the venue’s website must include structured data about each upcoming event. There are three ways to provide this structured data:
  1. Add HTML markup directly to the event listings. This is a good option if you have a custom event platform, want full control over all fields, and don’t mind a little coding.
  2. Use a markup-compatible events plugin or widget. This is an easy, reliable option if your events listing is powered by one of the supported platforms listed under Option 2 below.
  3. Rely on your venue's primary ticketer(s) to add structured data markup to their websites. Google will supplement the venue site's event listings with events found on ticketer websites.

Option 1: Add HTML Event Markup Directly

For websites whose HTML templates can be edited directly, the best approach is to add structured markup code to a page on the website that lists events. The page could be either the website’s home page; a page linked from the home page (e.g., my-venue.com/calendar); or individual “event details” pages for each event. If your event listings are spread over multiple pages, add markup to each page individually. Google will collect event details from all the pages it indexes on your site.
You can embed data in a web page using schema.org field names and the new JSON-LD data format. JSON-LD is easy to produce with many widely available JSON encoders. The data, enclosed within the <script type="application/ld+json"> ... </script> tags as shown in the examples below, may be placed in either the <HEAD> or <BODY> region of the page that displays that event. Either way, it won’t affect how your document appears in users’ web browsers.

Option 2: Use a Markup-Compatible Events Plugin or Widget

Some venue-oriented event management platforms have built-in support for adding structured data markup to the event listings they generate. If your site uses one of the following platforms or widgets, Google should understand your events automatically:

Option 3: Rely On Your Ticketer's Markup

Google can supplement a venue's event listings with events found on primary ticketer websites. If all of your venue's events are listed on a ticketer website that provides thorough structured data markup, you don't need to mark up your venue's website. However, note that events sourced from a ticketer site will show details links that click through to that ticketer, rather than to your venue site.
Examples of ticketers providing complete markup include: Ticketmaster, Ticketfly, TicketWeb, AXS, LaughStub, Wantickets, Holdmyticket, ShowClix, Stranger Tickets, Ticket Alternative, Digitick, See Tickets, Tix, Fnac Spectacles, Ticketland.ru, iTickets, MIDWESTIX, Ticketleap, and Instantseats.

Markup specification

Each event should be specified with the most specific applicable subtype of schema.org/Event. Popular subtypes include ComedyEvent, Festival, FoodEvent, MusicEvent, TheaterEvent, and SportsEvent. This helps search engines categorize your event, and in some cases lets you specify extra fields relevant to that type of event, such as the "homeTeam" and "awayTeam" for a SportsEvent, or the "workPerformed" for a TheaterEvent.
The following table indicates the full set of event fields used by Google from venue official websites:
PropertyTypeDescription
name (required)TextThe title of the event.
imageURLURL of an image or logo for the event or tour
urlURLURL of a page providing details about the event.
startDate (required)DateThe start date and time of the event, in ISO-8601 format.
doorTimeDateTimeThe time admission commences, in ISO-8601 format.
endDateDateThe end date and time of the event, in ISO-8601 format.
eventStatusEventStatusTypeThe event's cancellation status, if applicable. Must be one of the example values at right.
previousStartDateDateThe previously scheduled date (only if eventStatus is set).
typicalAgeRangeTextThe expected age range.
location (required)PlaceA nested schema.org/Place (or more specific subtype, such as schema.org/EventVenue or schema.org/PerformingArtsTheater).
location.name (required)TextThe venue name.
location.sameAsURLThe URL of the venue's official website.
location.address (required)PostalAddressThe venue's address. You may either provide the whole address as a single string, or provide the separate fields of the address in a nested schema.org/PostalAddress.
location.address.streetAddressThe street address.
location.address.addressLocalityThe locality or city.
location.address.addressRegionThe region or state.
location.address.postalCodeThe postal code.
location.address.addressCountryThe country code.
offersOfferA nested schema.org/Offer, one for each ticket type.
offers.url (recommended)The URL of a page providing the ability to buy tickets. This URL must:
  • direct to a landing page which clearly and predominantly provides, to any user from the general public, the opportunity to buy a ticket offering admittance to that specific event
  • be a link that is also present as a clickable link on the web page containing the data (i.e., not only in the markup)
  • be followable by the Googlebot, i.e., not blocked by robots.txt
offers.name [*]A user-visible name for the ticket type.
offers.category [*]Google recognizes the following values in this field:
  • primary: tickets available to the general public directly from the official representative of the event organizer or venue
  • secondary: tickets made available for resale after direct purchase
  • presale: tickets available early only to a subset of the public
  • premium: tickets with special benefits in addition to admission
Note: offers marked 'primary' will be given precedence in search contexts.
offers.price [*]The lowest available price, including service charges and fees, of this type of ticket.
offers.priceCurrency [*]The 3-letter currency code (unless included in price value).
offers.availability [*]The availability status of tickets.
offers.validFrom [*]The ISO-8601 date and time when tickets go on sale (only required on date-restricted offers).
offers.validThrough [*]The ISO-8601 date and time when tickets go off sale (only required on date-restricted offers).
performerPersonA nested schema.org/PerformingGroup or schema.org/Person, one for each performer.
performer.nameThe performer's name.
performer.sameAsThe URL of the performer's official website or Wikipedia page.
workPerformedCreativeWorkA nested schema.org/CreativeWork, used to represent each play, dance, or classical music piece being performed at the event (if applicable).
workPerformed.nameThe name of the creative work being performed.
workPerformed.sameAsThe URL of the work's Wikipedia page or other reference page.
awayTeam
homeTeam
SportsTeam(Pending schema.org proposal for SportsEvent only, where applicable.)
homeTeam.name
awayTeam.name
The name of the team.
homeTeam.sameAs
awayTeam.sameAs
The URL of the team's official website or Wikipedia page.

Markup examples: Concerts

The following examples show how to mark up venue event schedules. All examples are shown in JSON-LD syntax. Alternatively, you can mark up your content in microdata or RDFa syntax if you prefer.
<script type="application/ld+json">
[{
  "@context" : "http://schema.org",
  "@type" : "MusicEvent",
  "name" : "B.B. King",
  "startDate" : "2014-04-12T19:30",
  "location" : {
     "@type" : "Place",
     "name" : "Lupo's Heartbreak Hotel",
     "address" : "79 Washington St., Providence, RI"
  },
  "offers" : {
     "@type" : "Offer",
     "url" : "https://www.etix.com/ticket/1771656"
  }
},
{
  "@context" : "http://schema.org",
  "@type" : "MusicEvent",
  "name" : "B.B. King",
  "startDate" : "2014-04-13T20:00",
  "location" : {
     "@type" : "Place",
     "name" : "Lupo's Heartbreak Hotel",
     "address" : "79 Washington St., Providence, RI"
  },
  "offers" : {
     "@type" : "Offer",
     "url" : "https://www.etix.com/ticket/1771657"
  }
}]
</script>

Markup example: Theater performances

The following examples show alternate ways to mark up event information for theater performances. The markup represents a single performance; for multiple performance, simply repeat the markup for each performance. All examples are shown in JSON-LD syntax. Alternatively, you can mark up your content in Microdata or RDFa syntax if you prefer.
Theater performance: simple version - Basic full markup for a theater event. Theater performance: expanded/ticketer version - Markup for a theater event, including ticketing details.
<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "TheaterEvent",
  "name": "Julius Caesar at Shakespeare's Globe",
  "location": {
    "@type": "PerformingArtsTheater",
    "name": "Shakespeare's Globe",
    "sameAs": "http://www.shakespearesglobe.com/",
    "address": "London, UK"
  },
  "offers": {
    "@type": "Offer",
    "url": "/examples/ticket/0012301230123"
  },
  "startDate": "2014-10-01T19:30",
  "workPerformed": {
    "@type": "CreativeWork",
    "name": "Julius Caesar",
    "sameAs": "http://en.wikipedia.org/wiki/Julius_Caesar_(play)",
    "creator": {
      "@type": "Person",
      "name": "William Shakespeare",
      "sameAs": "http://en.wikipedia.org/wiki/William_Shakespeare"
    }
  }
}
</script>

Markup example: sports, comedy, and festivals

These examples show typical markup for sports events, comedy performances, and music festivals. All examples are shown in JSON-LD syntax. Alternatively, you can mark up your content in Microdata or RDFa syntax if you prefer.
<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "SportsEvent",
  "name": "Orioles at Red Sox",
  "startDate": "2014-09-10T13:35-0400",
  "location": {
    "@type": "StadiumOrArena",
    "name": "Fenway Park",
    "address": "4 Yawkey Way, Boston, MA 02215, United States",
    "sameAs": "http://boston.redsox.mlb.com/bos/ballpark/"
  },
  "awayTeam": {
    "@type": "SportsTeam",
    "name": "Baltimore Orioles",
    "sameAs": "http://baltimore.orioles.mlb.com/"
  },
  "homeTeam": {
    "@type": "SportsTeam",
    "name": "Boston Red Sox",
    "sameAs": "http://boston.redsox.mlb.com/"
  },
  "offers": {
    "@type": "Offer",
    "category": "primary",
    "url": "http://purchase.tickets.com/buy/MLBEventInfo?pid=7637107"
  }
}
</script>

FAQ for Venue Events Markup

My site's event listings are spread over multiple web pages. How should I mark it up?

It is fine to include markup on multiple pages of events; Google will collect event details from all the pages it indexes on your site. If using Data Highlighter, you can tag each page individually, or if there are many pages all formatted the same way, use the "Tag this page and others like it" option documented here.

Google is not showing a Knowledge panel for my venue. What can I do?

Knowledge Graph panel triggering is governed by a complex algorithm, but helpful steps you can take are to make sure that the venue is in both Wikipedia and Google My Business, and that the venue's official home page is recorded properly on both those sites.

It will take months to schedule the implementation of markup on my site. How can I make my site eligible for Google Events features in the meantime?

Yes, if you can't add schema.org markup, you can't use a supported CMS plugin or widget, and you can't rely on a primary ticketer to mark up all your venue's events, then you still have another option: Data Highlighter. Data Highlighter lets you "teach" Google to understand the pattern of your event listings without changing your HTML code at all. For this to work, your event listings must be formatted in a regular pattern — for example, in a table or list with each field shown consistently for each event, rather than in free-form text.
Data Highlighter is part of Google Webmaster Tools, so the first step is to get yourself verified to use those tools. Once you're verified, follow these step-by-step instructions to highlight and tag each key field of each event on your event listing page. When you're finished, Google will remember the pattern so that each time it crawls your site, it will understand any newly added or modified events. Note that if your site later undergoes a formatting change, you'll have to go back to Data Highlighter to teach it the new pattern. Also note that, unlike with Options 1 and 2, this option does not make your structured data available to other search engines. We recommend markup as a long-term solution for all authoritative event websites.

Google shows a Knowledge panel for my venue, but with no upcoming events. How do I troubleshoot this?

First, check that the events are shown correctly with no errors in the Structured Data Dashboard for the performer or venue's official website, as described above. If all fields look correct, report the missing events using the "Report feedback" link under the Knowledge Graph panel in Google search. Please report it via "Report something else" ... "Send general feedback", and be sure to use the term "events" in your description of the problem.

I use a plug-in or widget to list events on my site, but it's not on the list of supported widgets. What should I do?

Please forward this document to the author of the plug-in or widget and ask them to add markup!

Will Google recognize event markup in dynamically generated (e.g. AJAX) web pages?

JSON-LD markup inserted by Javascript that runs upon initial page load can be recognized. Other forms of markup in dynamic content are not supported.