Skip to content

How to query the infocenter

Concepts

All data in the infocenter is accessible without authorization, considering that we will add personalization functionalities soon we recommend to add the profile and authorization headers just like you do on the profile API as well.

The infocenter is one big pool of public data all over Switzerland and so far we did not add any restrictions for accessing the data by the partner. But you must comply with the guidelines described in the chapter data governance and the platform guidlines.

Our goal is to deliver quality data forming a graph expressed by json-ld.

Info

At the moment we provide a REST API only and can not offer a Graph-API like GraphQL.

Data Models

All our data models are based on the definitions of schema.org.

Definitions

Detailed information about the data models and their relations you can find in the discover.swiss data schema definition.

{
  "continuation": "...",
  "data": [
    {
    "identifier": "civ_px9-s28_bggg",
    "@id": "https://api.discover.swiss/info/v2/civicStructures/civ_px9-s28_bggg",
    "type": "schema.org/CivicStructure",
    "additionalType": "Museum",
    "dataGovernance": {
        "origin": [
            {
                "datasource": "zht-cms",
                "sourceId": "1666",
                "license": "CC BY-SA",
                "provider": {
                    "acronym": "zht",
                    "name": "Zürich Tourismus",
                    "logo": {
                        "contentUrl": "https://cdn.discover.swiss/logos/zht.jpg",
                        "@id": "https://api.discover.swiss/info/v2/imageObjects/img_px9_14w4",
                        "identifier": "img_px9_14w4"
                    },
                    "link": [
                        {
                            "url": "https://www.zuerich.com",
                            "type": "WebHomepage"
                        }
                    ],
                    "identifier": "zht"
                },
                "source": {
                    "acronym": "zht",
                    "name": "Zürich Tourismus",
                    "logo": {
                        "contentUrl": "https://cdn.discover.swiss/logos/zht.jpg",
                        "@id": "https://api.discover.swiss/info/v2/imageObjects/img_px9_14w4",
                        "identifier": "img_px9_14w4"
                    },
                    "link": [
                        {
                            "url": "https://www.zuerich.com",
                            "type": "WebHomepage"
                        }
                    ],
                    "identifier": "zht"
                }
            }
        ],
    },
    ...
  ]
}

Identity

Each Vertex in our graph has its unique identifier which represents exactly 1 object in the real world.

identifier schema.org/identifier which is used in the @id property to create the url
@id url to load the details of this object → https://json-ld.org/

Warning

Vertex identifiers can change if for example, the type in the source system is changing. Please see knowledge graph and Infocenter notification service how to handle identifier changes. An identifier should only change when the real-world object is changing. For example cities, they never change their type or name and will always have the same id.

Endpoints

We offer endpoints for all Vertex classes. Properties of values of types of other Vertex classes like "containedInPlace" or "images" contain a simplified model with just enough information to download the full object or in the case of the image display it.

sample endpoints:

  • /places
  • /places/{id}
  • /localbusinesses
  • /localbusinesses/{id}

At the current state, an endpoint delivers only objects of exactly this type and not derived types. For example a LodgingBusiness or AdministrativeArea is not contained in the list of places. But City is contained in AdministrativeArea endpoint because it has no additional property and technically it is an AdministrativeArea. The type schemaOrg.City is defined in the AdditionalType property.

Tip

You can use the search endpoints to retrieve polymorphic results.

All list endpoint deliver paged results.

Resolve vertex type

All objects should contain the @id property with the full URL to retrieve an object. In case you only have a discover.swiss id you need to resolve the type to be able to use the correct infocenter endpoint to retrieve the full object. In this case, you can retrieve the type via a search request so that you can use the correct endpoint afterwards to retrieve the full object.

link:

https://api.discover.swiss/info/v2/search

body:

{
    "filters": ["identifier eq 'loc_4kq_efajhifc'"],
    "select": "identifier, type",
    "facets": [],
    "project": ["demo-web"]
}

Localization

default: de-CH

Language: Based on the Accept-Language header localized properties are translated.

DateTime formatting: "2019-08-09T13:59:57.097+00:00"

Use Accept-Timezone header to specify request timezone. Supply a TimeZone id property acquired from Infocenter /timezones route or IANA code in order to get data with desired time offset

The default timezone is UTC

Number formatting: CH -> 250.00

Vertex deletion

The Infocenter system soft-deletes objects from the system. The object is removed from the graph but still available in the Infocenter. So they are still available for querying for a month. Deleted objects are not returned from the list and search endpoints but they will be returned by the specific GET endpoints with a property removed: true which indicates that the object was removed.

To get a list of deleted objects you need to provide the query parameter deleted with true value

Caching

In case you cache data delivered by Infocenter system on your side then it is best to select the data by project or containedInPlace query params so you can test on the entities endpoint if the changed object is still in your selection. When you retrieve a list of objects to compare against your own system you should use the select parameter to only retrieve the needed properties to faster retrieve and compare.

Next steps


Last update: August 29, 2022 06:12:17