Event recommendations β

Applicable sites

Sites that sell tickets to entertainment events, namely sites selling tickets to their own events and aggregator sites where tickets can be bought.

What it adds to search results

An answer with information about recommended venues and events for users, including dates and times.

How to set it up

To include your offers in such answers, provide up-to-date information about them to Yandex. To do this, create a YML feed, place it on your site, and add a link to the feed in Yandex Webmaster. The YML standard was developed by Yandex and is based on the XML standard.

The names of the shop and offer elements are used for backward compatibility with YML feeds and have no other meaning.

Feed restrictions

YML file size

200 MB

Total number of images

50,000

Number of images in one offer element

200

Number of offer elements

30,000. Data from a feed containing more offers will not be used for additional representation. The feed itself will load with an error. To have offers participate in the search, split the feed into several parts.

Don't duplicate offers with the same URL in multiple feeds, and also don't move offers from one feed to another — data from the moved offer may temporarily disappear from the search.

Number of elements set

1 million

The total number of all YML files (product feeds, service and offer feeds, RSS for content Turbo pages) for the site and its subdomains

1000

Example of a feed
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<yml_catalog date="2023-11-02T15:30">
    <shop>
        <name>MyActivities</name>
        <url>https://activities.s3.yandex.net</url>
        <picture>https://activities.s3.yandex.net/logo.png</picture>
        <categories>
            <category id= "1">Other</category>
            <category id= "2">Concert</category>
            <category id= "3">Theater</category>
            <category id= "4">Meeting</category>
            <category id= "5">Exhibition</category>
            <category id= "6">Performance</category>
            <category id= "7">Cinema</category>
            <category id= "8">Master class</category>
            <category id= "9">Lecture</category>
            <category id="10">Party</category>
            <category id="11">Show</category>
            <category id="12">Festival</category>
            <category id="13">Film screening</category>
            <category id="14">Excursion</category>
            <category id="15">Games</category>
            <category id="16">Sport</category>
            <category id="17">Stand-up</category>
            <category id="18">Puppet show</category>
            <category id="19">Ballet</category>
            <category id="20">Contest</category>
            <category id="21">Musical performance</category>
            <category id="22">Opera</category>
            <category id="23">Creative evening</category>
            <category id="24">Literary readings</category>
            <category id="25">Quest</category>
            <category id="26">Course</category>
            <category id="27">Musical</category>
            <category id="28">Training</category>
            <category id="29">Discussion</category>
            <category id="30">Monologue</category>
            <category id="31">Christmas trees</category>
            <category id="32">Seminar</category>
            <category id="33">Fair</category>
            <category id="34">Plastic performance</category>
            <category id="35">Presentation</category>
            <category id="36">Performance art</category>
            <category id="37">Circus</category>
            <category id="38">Literary evening</category>
            <category id="39">Conference</category>
            <category id="40">Operetta</category>
            <category id="41">Tasting</category>
            <category id="42">Play reading</category>
            <category id="43">Immersive theater</category>
            <category id="44">Water tours</category>
            <category id="45">Quest game</category>
            <category id="46">Flash mob</category>
            <category id="47">Ball</category>
            <category id="48">Competition</category>
            <category id="49">Online broadcasts</category>
            <category id="50">Audio drama</category>
            <category id="51">Attractions</category>
            <category id="52">Ice rinks</category>
            <category id="53">Casting</category>
            <category id="54">City holidays</category>
        </categories>
        <offers>
            <!-- Valid offer expample -->
            <offer id="unique-offer-id">
                <categoryId>7</categoryId>
                <currencyId>RUB</currencyId>
                <price>100</price>
                <name>Seven Psychopaths</name>
                <description>A crime comedy by director Martin McDonagh, known for the films "In Bruges" and "Once Upon a Time in Ireland."</description>
                <url>https://activities.s3.yandex.net/movie/sem-psihopatov?utm_source=yandex-what-to-do&amp;utm_medium=msk</url>
                <picture>https://activities.s3.yandex.net/images/movie/poster/c9/98/poster1.jpg</picture>
                <picture>https://activities.s3.yandex.net/images/movie/8c/bc/screenshot1.jpg</picture>
                <picture>https://activities.s3.yandex.net/images/movie/c6/48/screenshot2.jpg</picture>
                <param name="short_name"></param>
                <param name="short_descritpion"></param>
                <param name="event_id">2934</param>
                <param name="tags">movie;comedy</param>
                <param name="participants">Colin Farrell,actor;Woody Harrelson,actor;Martin McDonagh,director</param>
                <param name="age_restriction">18+</param>
                <param name="videos"></param>
                <param name="is_free">false</param>
                <param name="is_online">false</param>
                <param name="has_tickets">true</param>
                <param name="place_name">cinema "Five Stars" at Novokuznetskaya</param>
                <param name="place_address">Moscow, Bolshoy Ovchinnikovsky Lane, 16</param>
                <param name="place_city">Moscow</param>
                <param name="place_country_code">RU</param>
                <param name="place_lon">37.63013889999958</param>
                <param name="place_lat">55.74446700000007</param>
                <param name="place_timezone">Europe/Moscow</param>
                <param name="place_phones">8(495)212-85-06;8(495)212-85-07</param>
                <param name="place_urls">https://5zvezd.ru/;https://activities.s3.yandex.net/cinemas/123</param>
                <param name="start_date">2023-11-02</param>
                <param name="start_time">21:55:00</param>
                <param name="prices">100;200;300</param>
                <param name="duration_min">110</param>
            </offer>
        </offers>
    </shop>
</yml_catalog>
Feed format
Description of "shop" — information about the source

Element

Type

Description

Required

name

String

Source name. Displayed in the price list and in the event description caption.

Yes

url

String

A link to the source site. The domain must match the event (offer) domain.

Yes

picture

String

A link to the source's logo. Displayed next to the source name in the price list.

Recommended size: 32 × 32 pixels. Recommended format: PNG. The size affects the image quality in search results.

Yes

categories

List[String]

A list of categories in the feed.

A category is a general description of the event, indicating its format. Category examples: Movie, Play, Concert, Workshop.

The category determines which section the event will be displayed in and affects the quality of recommendations.

One event can have only one category. You can use tags to categorize the event more accurately.

You can use categories and their categoryId values from the feed example. Don't add any categories that your feed has no events for.

Yes

Description of "offer" — information about the event (offer)

An offer is an individual element of the schedule. This element should contain information about the event, its venue, and when it takes place. If it's a long event, such as an exhibition, specifying the end time is enough: param name="end_date". If it's a recurring event, create multiple offers with the same param name="event_id" and other fields, but with different schedules.

Element

Type

Description

Required

categoryId

Int

The event category ID. Selected from the categories list in the shop description.

Used for categorization, filtering, and relevant recommendations.

Yes

currencyId

String

The currency code in ISO 4217 format. For example, USD, RUB, or EUR.

Yes

price

Float

The minimum event ticket price.

For free admission, enter "0" and set param name="is_free" to true. If you only enter "0", the price is considered undefined.

Yes

name

String

The event name in Russian. Displayed in the event preview and in the detailed information.

Yes

description

String

Full description of the event with HTML markup. Displayed in the detailed event information.

Yes

url

String

A link to the event page.

Example: https://kudago.com/msk/event/teatr-vernuvshiesya-inaya-realnost/.

Yes

picture

String

Links to original images of the event.

Yes

param name="short_name"

String

A short name for the event in Russian. Displayed in the event preview in search results.

No

param name="short_description"

String

A short description of the event with HTML markup. Currently, this element isn't used.

No

param name="event_id"

String

A unique event ID. Used for providing recommendations.

Yes

param name="tags"

String

A list of event tags separated by semicolons, like this: melodrama;comedy.

Used for filtering events and providing personalized recommendations.

Tags affect the quality of recommendations. An event with many general tags may be outranked by events with more specific tags in the category selected by the user. At the same time, adding tags that are too narrow may significantly limit the event's outreach.

No

param name="participants"

String

A list of event participants in the following format: "Name of participant 1,Role of participant 1;Name of participant 2,Role of participant 2".

Example: Colin Farrell,actor;Woody Harrelson,actor;Martin McDonagh,director.

No

param name="age_restriction"

String

Age restriction.

Displayed in the preview and in the detailed event information. Possible values: 0+, 6+, 12+, 16+, 18+.

Yes

param name="videos"

String

A list of links to event videos.

The first video is used as a preview in the event card. The other videos are displayed in the detailed event description.

No

param name="is_free"

Boolean

A flag indicating that the event is free.

Used for filtering events and providing recommendations.

The default value is false.

No

param name="is_online"

Boolean

A flag indicating that the event is held online. Used for filtering events and providing recommendations.

No

param name="has_tickets"

Boolean

Whether tickets to the event can be bought. For free admission, set to true.

The default value is true.

No

param name="place_name"

String

Venue name.

Displayed in the detailed event information.

Yes

param name="place_address"

String

Full venue address: the locality, street name, and house number.

Displayed in the detailed event information.

Yes

param name="place_city"

String

The city where the venue is located.

Yes

param name="place_country_code"

String

The country code in ISO-3166 alpha-2 format. Currently, only the "RU" region is supported.

Yes

param name="place_lon"

Float

The venue's longitude.

Used for displaying the event's placemark on the map.

No

param name="place_lat"

Float

The venue's latitude.

Used for displaying the event's placemark on the map.

No

param name="place_timezone"

String

The venue's time zone in IANA format.

Yes

param name="place_phones"

String

A list of the event organizers' phone numbers.

No

parma name="place_urls"

String

A list of links to the venue's sites.

For example, you can include a link to the venue's page in your service, a link to the venue's page on a social media platform, and a link to the venue's own site.

No

param name="start_date"

String

The event start date in local time, formatted as YYYY-MM-DD (ISO-8601). For example: 2023-04-07.

Used for selecting events falling on a specific date or within a period.

Can be left empty for events where the exact time doesn't matter or for long events, such as exhibitions.

Not required only if param name="end_date" is set, otherwise the event won't be displayed.

param name="start_time"

String

The event start time (local), formatted as HH:MM:SS (ISO-8601). For example: 14:00:00.

Used for selecting events falling on a specific date or within a period.

Can be left empty for events where the exact time doesn't matter or for long events, such as exhibitions.

No

param name=”duration_min”

Int

The event duration in minutes.

No

param name="end_date"

String

The event end date in local time, formatted as YYYY-MM-DD (ISO-8601). For example: 2023-04-17.

Used for selecting events falling on a specific date or within a period.

This field is particularly important for correctly filtering long events, such as exhibitions.

Can be left empty for short events, such as plays.

Not required only if param name="start_date" is set, otherwise the event won't be displayed.

param name="end_time"

String

The event end time (local), formatted as HH:MM:SS (ISO-8601). For example: 14:00:00.

Used for selecting events falling on a specific date or within a period.

Can be left empty for short events, such as plays.

This field is particularly important for correctly filtering long events, such as exhibitions.

No

param name="prices"

Float

A list of ticket prices for this time at this place.

A list of integers separated by semicolons, like this: 100;200;300.

Used for filtering events by price and providing recommendations.

For long events, specifying all the prices is enough. You don't need to assign the prices to different days of the week.

Prices are fractions accurate to two decimal places.

No

param name="offer_url"

String

A link for buying tickets to the event.

Takes the user to the ticket purchase page. If this field isn't set, the link to the event page is used (url).

No

How to send a feed

You can upload your feed:

Log in to Yandex. Add the site to Yandex Webmaster and verify your management rights, or get access for your account from the site owner.

  1. Go to the Services and offers in search → Feeds and errors page in Yandex Webmaster.

  2. Click Upload feed.

  3. Choose the Things to do business category.

  4. Specify the region. For example, if offers in the feed are available on the same terms in all regions, select Russia.

  5. In the Link to file with offers field, enter the URL that looks like https://example.com/feed.yml.

    If your site has authorization configured to access the YML file, you can send the username and password along with the URL which it's available at. For example: http://yandex:WE9h4FfBml@example.com/feed.yml.

  6. Click Done.

For more information, see documentation.

Yandex Webmaster will check the feed. If it contains errors, a message about errors will appear next to the feed on the Services and offers in search results → Feeds and errors page in Yandex Webmaster. To open them, click View. Fix the errors, and Yandex Webmaster will check the feed again after a certain amount of time.

Terms

The site must ensure that the data is correct and the offers match the subject. It is also responsible for dissemination of illegal information. In the event the terms are violated, Yandex has the right not to use the site data for changing the display in the search results.

Page updated: January 16, 2024.

Change history
  • Updated the description of the place_country_code parameter: currently, only the "RU" region is supported.
Subscribe to updates



You can also go to