Open Data: Version 2.0

This document describes the open data API of zuerich.com for retrieving information about locations and accommodation locations published on the site. The entities are structured according to Schema.org. Standard properties are structured like the properties of the according types in Schema.org like openingHours for a LocalBusiness. Each of these entities are also tagged with one or more categories. The following objects can be retrieved via the API:

• Locations like restaurants, museums, points of interest
• Accommodations

The API is available for the domains of Zürich Tourism, Rapperswil Zürichsee Tourismus, and Einsiedeln-Ybrig-Zürichsee. The main endpoints of the API are located at:

• zuerich.com/en/api/v2/data
• rapperswil-zuerichsee.ch/en/api/v2/data
• eyz.swiss/en/api/v2/data

The API can be used to retrieve all the available categories, or to retrieve all the objects tagged with a specific category. See the following sections for more detailed instructions.

The following data sets are available. A description of the API for using the data can be found further down on this page, using the domain zuerich.com as example. The other domains (Rapperswil Zürichsee & Einsiedeln-Ybrig-Zürichsee) are following the same logic.

A catalog overview of the zuerich.com data is also available on the Open Data Portal of the City of Zurich.

By just calling the endpoint, https://www.zuerich.com/en/api/v2/data, without any other parameters, the result is a list of all the available categories. The category items are stored as a hierarchical tree, so each of the category item has also a reference to its parent. If the parent is 0, then the category is a root item. An excerpt from the result list can be seen bellow:

 [   {     "id": "201",     "parent": "166",     "swissId": "culinary-dinner",     "name": {       "de": "Abendessen",       "en": "Dinner",       "fr": "Dîner",       "it": "Cena"     },     "path": "/data?id=201"   },   {     "id": "71",     "parent": "0",     "swissId": "",     "name": {       "de": "Übernachten",       "en": "Accommodation",       "fr": "Logement",       "it": "Ospitalità"     },     "path": "/data?id=71"   } ]

The id represents the internal id of the category. The parent represents the id of the parent for the category item. If 0, the category is a root item. The name represents the actual name or label of the category (this is a translatable field) and the path contains the location where all the objects tagged with the respective category item can be found. The swissId  is a unique category identifier from discover.swiss. 

By appending the path of a category to the API endpoint, you can get all the objects which are tagged with that respective category. For example, to get all the objects tagged with American, the following path can be used https://www.zuerich.com/en/api/v2/data?id=193. The result would be a list of all the American cuisine restaurants, for example:

  [   {     "@context": "https://schema.org/",     "@type": "LocalBusiness",     "identifier": "556900",     "copyrightHolder": {       "de": "Zürich Tourismus www.zuerich.com",       "en": "Zurich Tourism www.zuerich.com",       "it": "Zürich Tourismo www.zuerich.com",       "fr": "Zürich Tourisme www.zuerich.com"     },     "license": "BY-SA",     "category": [       "Restaurants",       "Cuisine",       "American",       "Meal",       "Lunch",       "Dinner",       "Coffee",       "Tea",       "Relaxed and Cozy",       "Lively and Cheerful"     ],     "name": {       "de": "Bagel Boys",       "en": "Bagel Boys",       "fr": "Bagel Boys",       "it": "Bagel Boys"     },     "disambiguatingDescription": {       "de": "Ganz nach dem Vorbild der berühmten New Yorker Bagelshops servieren auch die Bagel Boys das runde Gebäck mit Loch in diversen Varianten.",       "en": "Modeled on the famous New York bagel stores, the Bagel Boys also serve this round bread roll with a hole in the middle in all kinds of mouthwatering variations.",       "fr": "Comme les très réputés magasins de bagels new-yorkais, les Bagel Boys proposent diverses variantes de ces petits pains ronds en forme d’anneau.",       "it": "Ispirandosi ai famosi bagel shop di New York, anche Bagel Boys serve il panino rotondo col buco in diverse varianti."     },     "description": {       "de": "<p>Ob mit Pastrami, selbst geräuchtertem Lachs, in einer vegetarischen oder veganen Variante: Bei den Bagel Boys in Zürichs Norden bekommen alle den Bagel ihrer Wahl.</p>\r\n\r\n<p>Nach dem Vorbild der berühmten Bagelshops in New York werden die Bagel alle handgefertigt und in der hauseigenen Bäckerei gebacken. Gefüllt werden diese mit den besten und mehrheitlich biologischen Zutaten.</p>\r\n\r\n<p>Neben einer riesigen Auswahl an Bagel ist das Restaurant mit Bäckerei auch auf amerikanisches Süssgebäck spezialisiert. Zum Nachtisch gibt es daher Blueberry Muffins, Brownies und Cheesecakes.</p>\r\n",       "en": "<p>Whether with pastrami, with self-smoked salmon, or as a vegetarian or vegan variant: at the Bagel Boys in the north of Zurich, everyone will find their favorite bagel.</p><p>Modeled on the famous bagel stores in New York, all the bagels are hand-made and baked in the in-house bakery. They are filled with top-quality and mostly organic ingredients.</p><p>Besides a huge selection of bagels, the restaurant, which also houses a bakery, specializes in American sweet pastries. For dessert there are blueberry muffins, brownies, and cheesecakes.</p>",       "fr": "<p>Avec pastrami ou saumon fumé maison, végétarien ou végan : chacun choisit le bagel de son choix chez les Bagel Boys du nord de Zurich.</p><p>Comme les très réputés magasins new yorkais, les bagels sont artisanaux et cuits dans la boulangerie du magasin, puis garnis avec les meilleurs ingrédients pour la plupart bios.</p><p>Outre le vaste choix de bagels, ce restaurant avec boulangerie s’est spécialisé dans la pâtisserie américaine. En dessert sont proposés des muffins blueberry, brownies et cheesecakes.</p>",       "it": "<p>Con pastrami, salmone affumicato in casa, vegetariani o vegani: da Bagel Boys, a Zurigo nord, tutti trovano il bagel che preferiscono.</p><p>Come accade nei famosi bagel shop di New York, anche qui i bagel sono tutti fatti artigianalmente e cotti al forno nel panificio della casa. Per imbottirli, si usano solo gli ingredienti migliori, in gran parte biologici.</p><p>Oltre a un’ampia selezione di bagel, il ristorante con panificio è specializzato anche in dolci americani. Per dessert, ci sono quindi muffin ai mirtilli, brownies e cheesecake. </p>"     },     "titleTeaser": {       "de": "Bagel Boys",       "en": "Bagel Boys",       "fr": "Bagel Boys",       "it": "Bagel Boys"     },     "textTeaser": {       "de": "Lecker gefüllte Bagel und amerikanisches Gebäck wie Muffins und Brownies stehen hier im Zentrum.",       "en": "The focus here is on deliciously filled bagels and American pastries, such as muffins and brownies.",       "fr": "Délicieux bagels fourrés, muffins et brownies américains sont à l’honneur.",       "it": "Squisiti bagel imbottiti e dolci americani come muffin e brownies sono i protagonisti del locale."     },     "detailedInformation": {       "de": [         "Handgefertigte und -gebackene Bagel",         "Frische und biologische Zutaten",         "Amerikanisches Süssgebäck"       ],       "en": [         "Hand-made and self-baked bagels",         "Fresh and organic ingredients",         "American sweet pastries"       ],       "fr": [         "Bagels cuits faits main",         "Ingrédients bio frais",         "Desserts américains"       ],       "it": [         "Bagel artigianali cotti al forno",         "Ingredienti freschi e biologici",         "Dolci americani"       ]     },     "image": {       "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32352.jpg",       "caption": {         "de": "Bagel Boys",         "en": "",         "fr": null,         "it": null       }     },     "price": {       "de": null,       "en": null,       "fr": null,       "it": null     },     "photo": [       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32344.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32346.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32348.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32350.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32351.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32353.jpg",         "caption": {           "de": null,           "en": "Bagel Boys",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32354.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32357.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32360.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32363.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       },       {         "url": "https://www.zuerich.com/sites/default/files/web_zuerich_bagel_boys_1280x960_32364.jpg",         "caption": {           "de": "Bagel Boys",           "en": "",           "fr": null,           "it": null         }       }     ],     "dateModified": "02.12.2020 09:12",     "opens": [       "Monday",       "Tuesday",       "Wednesday",       "Thursday",       "Friday",       "Saturday",       "Sunday"     ],     "openingHours": [       "Mo,Tu,We,Th,Fr 700-1800",       "Sa,Su 800-1400"     ],     "specialOpeningHoursSpecification": {       "de": null,       "en": "<p>Monday &ndash; Friday, 7am &ndash; 6pm<br />Saturday &amp; Sunday, 8am &ndash; 2pm</p>",       "fr": "<p>Du lundi au vendredi, 7h &ndash; 18h<br />Samedi et dimanche, 8h &ndash; 14h</p>",       "it": "<p>Da lunedì a venerdì, 07.00 &ndash; 18.00<br />Sabato e domenica, 08.00 &ndash; 14.00</p>"     },     "address": {       "addressCountry": "CH",       "addressLocality": "Zürich",       "postalCode": "8050",       "streetAddress": "Dialogweg 11",       "telephone": "+41 44 310 20 80",       "email": "info@mybagel.ch",       "url": "https://mybagel.ch/page/restaurant"     },     "geoCoordinates": {       "latitude": 47.414053000000003,       "longitude": 8.5592299999999994     },     "place": [       "Indoors",       "Outdoors"     ]   } ] 

There are, however, a few custom fields which are not schema.org standard. The full list of non-standard fields, per each object type, can be seen bellow. (Since we have now more specific types, the type column also includes all its children types)

Some of the fields support translations. For those fields, the returned value is actually an object containing the language codes as properties and the actual field, translated in that language, as value. The fields which do not support translations will just return their value directly. As an example here the fields from the Unmeat Restaurant. The field opens contains its value directly while textTeaser has the mentionend translation strucutre.

"opens": [
 "Tuesday",
 "Wednesday",
 "Thursday",
 "Friday",
 "Saturday",
 "Sunday"
 ]

"textTeaser": {
"de": "Leckere Burger, fettige Fritten und Saucen, die’s in sich haben: Unmeat überzeugt nahe der Langstrasse.",
"en": "Delicious burgers, greasy fries, and sauces oozing with flavor: Unmeat near Langstrasse has it all.",
"fr": "Délicieux burgers, frites à la graisse et sauces copieuses : le Unmeat près de la rue Langstrasse a tout pour séduire.",
"it": "Gustosi burger, patatine bisunte e salse buonissime: l’Unmeat convince vicino alla Langstrasse."
}

Change for description field

The description field got an upgrade to a full wysiwyg field with the following allowed tags: "<em><strong><code><ul><ol><li><dl><dt><dd><h2><h3><h4><h5><h6><img><h1><pre><p><a><table><caption></caption><tbody><thead><tfoot><th><td><tr><br>".
In Open Data V1 there were just <p> tags allowed.

Endpoint only in English

There's a redirect for other languages and the endpoint for version 2 is only available in English.

More possible values in the @type field

In version 1 there were only 3 possible types 

• LodgingBusiness for accommodations (https://schema.org/LodgingBusiness).
• Place for places (https://schema.org/Place).
• LocalBusiness for restaurants / cafes (https://schema.org/LocalBusiness).

In version 2 the possible values get expanded to all children types of event (https://schema.org/Event), place (https://schema.org/Place), organization (https://schema.org/Organization) and creativeWork (https://schema.org/CreativeWork)

New custom type field

Our accommodations and locations have types according to schema.org. There are some special cases where there is a more specific custom type. In that case the new custom type will be provided in the @customType field and its schema.org parent will be in the @type field.

Opening hours

The field openingHoursExceptions was renamed to openinghoursSpecification. So if there are opening hours exceptions they are in the openingHoursSepcification field structured like:

"opens": [
      "Monday",
      "Tuesday",
      "Wednesday",
      "Thursday",
      "Friday",
      "Saturday"
    ],
    "openingHours": [
      "Mo,Tu,We,Th,Fr 07:00:00-23:00:00",
      "Sa 07:00:00-00:00:00"
    ],
    "openingHoursSpecification": [
      {
        "@type": "OpeningHoursSpecification",
        "validFrom": "2022-07-17",
        "validThrough": "2022-07-17",
        "opens": "08:15:00",
        "closes": "17:30:00"
      }
    ],
    "specialOpeningHoursSpecification": {
      "de": null,
      "en": null,
      "fr": null,
      "it": null
    }

The field for the opening hours there are 2 new cases:

• Seasonally closed: there are locations which are seasonally closed. If that's the case data will be provided like this

"opens": null,
"openingHours": null,
"openingHoursSpecification": null,
"specialOpeningHoursSpecification": {
    "de": "Saisonbedingt geschlossen von Mittwoch, 15. Juni 2022 bis Samstag, 30. Juli 2022.",
    "en": "Seasonally closed from Wednesday, 15 June 2022 until Saturday, 30 July 2022.",
    "it": "Chiuso stagionalmente da Mercoledì 15 Giugno 2022 a Sabato 30 Luglio 2022.",
    "fr": "Fermeture saisonnière du Mercredi 15 juin 2022 au Samedi 30 juillet 2022."
}

• Always open: Locations like public parks and so on are open around the clock. If that's the case data will be provided like this

"opens": null,
    "openingHours": null,
    "openingHoursSpecification": null,
    "specialOpeningHoursSpecification": {
      "de": "Rund um die Uhr geöffnet",
      "en": "Open around the clock",
      "it": "Aperti tutto il giorno",
      "fr": "Ouvert 24 heures sur 24"
    }

New non-standard field tomasBookingId

There's a new field for all children types of LocalBusiness with the Tomas booking ID which is a direct reference to the Tomas system.

The data published here is available free of charge and can be freely reused under a CC BY-SA license. The data may be:

• Reproduced, disseminated and made available to others.
• Augmented and edited.
• Used commercially.