Skip to content

How to work the the infocenter

Concepts

The infocenter is one big pool of public data all over Switzerland. Depending on the source systems license some objects are restricted to specific partners e.g. to use Guidle Data you need to have an agreement with Guidle. 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. At the moment we provide a REST API only and do not offer a Graph-API like GraphQL.

API usage

The API is secured with a subscription key which you can create in the Developer Portal. Follow the instruction on How to get access to the API to create your own subscription.

You can use the Infocenter API without a paid infocenter package. With this restricted access, you can retrieve all objects with an open license. The following restrictions applies to users without an infocenter package:

  • You can't use the search functionality
  • You can't get weather data on POIs
  • You can't use Media Service to access pictures (e.g. crop them automatically, access over CDN, automatically include Bibliography on the pictures etc.)
  • The number of calls is restricted to 60 per minute and 50'000 per month

All data in the infocenter is accessible without authorization. If you are using the Profile Service functionality then considering to add the profile or authorization header just like you do on the Profile API as well because we will add personalization functionalities soon to the search endpoints.

If the rate limit is reached then 429 Too Many Requests will be returned with the following body:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in 49 seconds."
}

If the monthly quota is reached then 403 Quota Exceeded will be returned with the following body:

{
    "statusCode": 403,
    "message": "Out of call volume quota. Quota will be replenished in 29.23:36:46"
}

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.

Robots

  • Robots Meta Tag as defined by Google.
    This value is dependent on the project in the request and can be noindex or index.

Please use the value provided in the API in the robots tag of your page where the object is displayed.

Next steps


Last update: February 1, 2024 17:37:15