Mark Up Your Lists

When you use structured data to mark up items for lists, you make your content eligible for inclusion in a sequence-based UI in Search. Users can easily swipe or scroll through a list of cards showing a preview of your site from their Search results, which leads them more quickly to the right content on your site. This document describes how to mark up two types of lists:

  • Host-specific lists—displays cards from a single site within a specific category. This markup uses a combination of ItemList markup and individual data type markup to enable a carousel of lists to appear in Search.
  • Events—enables a carousel of events from authoritative event websites.

Mark up host-specific lists

Build your list pages with AMP HTML and use two types of markup to make your content eligible for a host-specific list:

  • List Page markup—this markup specifies the list, its items, and their order.
  • Item-specific markup—this markup notes the properties for the data type you want to have in the list, such as name and prepTime for recipes.

List markup

Provide markup for the ItemList data type by using these required properties.

Property Type Description
itemListElement (Required) ListItem Annotation for a single item page.
ListItem.position (Required) Integer Ordinal position of the item page in the list.
ListItem.url (Required) URL The canonical URL of the item page. Every item should have a unique URL.

Data type markup

To enable host-specific lists, you first expose the data type properties you want to make available for presentation in your list, such as an image, a description, and other relevant details. Mark up each item in the list (i.e., recipe, movie, or restaurant listing) with the required structured data markup. While the requirements are minimal, you can include recommended markup to enhance the appearance in the search result. Check the documentation for each data type to see the specific requirements.

How to mark up host-specific lists

You can mark up your lists in two ways:

  • Separately—When a recipe has its own page, use data type markup on individual item pages. Use list page markup on the summary page that links out to the items. If you use this method, the visible content on the summary page must contain the same content that you specify in the markup, such as your site’s listing of user’s favorite dinner recipes. See Structured data guidelines in Introduction to Structured Data for specifics.
  • Combined—When multiple recipes are on a single page, use list page markup that both itemizes the data types and exposes their properties in the item field.

    In this case, be sure to include a unique URL for each item, which in this case might include an anchor tag.

The examples below open markup in the Structured Data Testing Tool for ItemList markup.

List-only markup

Recipe and list markup

Recipe-only markup

Mark up event listings

Millions of users ask Google questions about upcoming events every day —but to answer those questions well, Google needs structured data directly from the most authoritative websites for each event. This documentation describes how event organizers, performers, venues, ticketers, and hosting platforms can participate directly in event Search features.

As with markup for host-specific recipe lists, you will need to mark up the event information on your site using the Event data type and provide the relevant properties for your events. You do not need to provide list markup in order for your events to appear in an event carousel in Search results.

For event-specific examples, guidelines, and data type properties, see the data type reference for Events.

Use one of the following methods to provide structured data for Events:

  1. Embed event data type markup directly to the event listings.

    Primary ticketers should use this option. This is also a good option if you have a custom event platform, want full control over all fields, and don’t mind a little coding. It is fine to include markup on multiple pages of events; Google collects event details from all the pages it indexes on your site. JSON-LD markup inserted by JavaScript that runs upon initial page load is also recognized.

  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 described in the Event data type reference under Supported markup widgets and plugins. If you don’t see your widget or plugin on the list, ask your content management plugin provider to support event markup.

  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.

Troubleshooting events in Knowledge Graph cards

Knowledge Graph card display is governed by a complex algorithm, so if you don’t see your artist or your artist’s events in the Knowledge Graph card, try these steps:

  • 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.
  • For events missing from a Knowledge Graph card, check that the events are shown correctly with no errors in the Structured Data Testing Tool. If all fields look correct, report the missing events using the Feedback link under the Knowledge Graph card in Google search. Please report it as general feedback and be sure to use the term events in your description of the problem.

Send feedback about...