Friday, 10 July 2015

Event Markup: Official Performer Sites

Google shows upcoming event listings for performers, like musical artists and comedians, to millions of users each day in Google products. With your events displayed on Google, your fans can easily see event details and learn where to buy tickets. To be eligible for these features and to ensure that Google has the right data, provide up-to-date event schedules in 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: 

Providing event data on performer sites

Google’s new approach to organizing event data depends on finding complete event information on each performer’s official website. Human-readable event listings are not sufficient; instead, the performer’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. (New) Use "delegation markup" to instruct Google to get your event listings from a page on another website.

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.,; 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 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 band-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, Google should understand your events automatically:
Similarly, if your website shows its event listings by embedding the "widget" of an events database service, Google should be able to read your events from that widget. Google supports the following widgets:

Option 3: Delegate Your Event Listings to Another Website

What if you can’t add markup or an event widget to your official website — for example, if your website doesn’t list your events at all? A new option is delegation markup: a way to specify that your events should be sourced from another web page of your choice. Just add markup like this, customizing the three bolded values, to your home page:
    <script type="application/ld+json">
    {"@context" : "",
     "@type" : "MusicGroup",
     "name" : "Your Band or Performer Name",
     "url" : "",
     "event" : ""
Google will follow the “event” URL provided to find your events. For those events to be usable, the following conditions must be met:
  • The target page must be accessible to the Googlebot (not blocked by robots.txt).
  • The target page must contain structured data items of type (or its subtypes, like
  • Each of those Event items must specify a performer property corresponding to the performer.
Examples of URLs that may be specified as targets of the “event” property include:
Note that attribution links for the events sourced from the delegate site will link to that site, not to your official site.

Markup specification

When implementing event markup directly, each event should be specified with the most specific applicable subtype of 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 Google uses from performer official websites:
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 (or more specific subtype, such as or (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
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, 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, as well as markup with offer details
  • 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 [*]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 or, one for each performer.
performer.nameThe performer's name.
performer.sameAsThe URL of the performer's official website or Wikipedia page.
workPerformedCreativeWorkA nested, 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.
SportsTeam(Pending proposal for SportsEvent only, where applicable.)
The name of the team.
The URL of the team's official website or Wikipedia page.
[*] Note: If your website doesn't perform ticketing on-site, you only need to mark up the url field of each offer. Google will follow that url to a ticketer website and retrieve the other Offer details from that site. If your website does perform ticketing, it should mark up all Offer properties listed.

Markup example: concert information

The following examples show how to mark up concert event information. All examples are shown in JSON-LD syntax, which we recommend. Alternatively, you can mark up your events in microdata or RDFa syntax if you prefer.
  • Concert: simple version -- Basic markup for two concerts.
  • Concert: expanded/ticketer version -- A more fully specified concert event, including a tour image, full venue address, multiple performers, and multiple ticket classes. In general, the more fields specified, the more information about the event Google can present to Google users.
  • Classical music concert -- In this example, the performer and workPerformed properties are provided. In the future this will enable Google to show this event on a variety of user searches: "Chicago Symphony Center", "Chicago Symphony Orchestra", and even "Shostakovich Symphony #7".
  • Comedy events -- Basic markup for two comedy shows.
<script type="application/ld+json">
  "@context" : "",
  "@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" : ""
  "@context" : "",
  "@type" : "MusicEvent",
  "name" : "B.B. King",
  "startDate" : "2014-04-13T20:00",
  "location" : { 
     "@type" : "Place",
     "name" : "Lynn Auditorium",
     "address" : "Lynn, MA, 01901"
  "offers" : {
     "@type" : "Offer",
 "url" : ""

FAQ for Performer 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 Graph panel for my performer. 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 artist is in both Wikipedia and MusicBrainz, and that the artist'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?

If you can't add markup and you can't use a supported CMS plugin or widget, then you still have two other options: Delegated Markup, as described above, and 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 markup-based options, 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 performer, 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 as "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?

Yes, JSON-LD markup inserted by Javascript that runs upon initial page load can be recognized.