Skip to content

Facets

There are next facets in the response:

facet name filter property name filter value type description
address/addressLocality addressLocality string[]
address/postalCode addressPostalCode string[]
tag tag string[] List of common discover.swiss tags. Profile and Campaign tags were not included.
campaignTag campaignTag string[] List of campaign tags.
categoryTree categoryTree string[] represent category tree list. For getting full list of categories don't forget to set big enough value for count property in facet request
containedInPlace/id containedInPlace string[]
time time int[]
length length double[] Length of tour
state state string[]
rating/condition ratingСondition int[]
rating/difficulty ratingDifficulty int[]
elevation/ascent elevationAscent int[]
elevation/descent elevationDescent int[]
elevation/minAltitude elevationMinAltitude int[]
elevation/maxAltitude elevationMaxAltitude int[]
season season string[]
type type string[]
combinedType combinedType string[] represent array containing data from parentType and parentAdditionalType properties
combinedTypeTree combinedTypeTree string[] represent array containing tree data from parentType and parentAdditionalType properties
leafType leafType string[] contains additionalType or type
sourcePartner sourcePartner string[] contains list of source partner acronyms

see search facet response

see search facet value response

Attention

It is important to use single quotes with 'string' value type and don't use single quotes with int value type

Warning

To get the full list of categories don't forget to set big enough value for count property in facet request

Control of facets through facet request

Use POST requests to get more control under the facets responses.

Attention

Possibility to pass an array of facets request exists only in POST request.

Search facet request

Parameter Type Description
name string name of facet or value from filterPropertyName property that will be in the response of search (e.g. rating/condition and ratingCondition returns same facet)
responseName string value which will be returned in the FacetResponse.Name property. If it is null then a default name will be returned for the current facet
values string property that represent borders for range response
interval int property that represent interval borders for range response
count int count of facets in the reponse
selectValues string[] facet values which will be returned in the response. If selectValues is set then filterValues, values or interval can't be used. If selectValues contains values then the value of count will be equals to max int (2,147,483,647)
filterValues string[] facet values which will be returned in the response. If filterValues is set then selectValues, values or interval can't be used. If filterValues contains values then the value of count will be equals to max int (2,147,483,647)
scope string represent type of scope which will be used for building response. Possible values: ["all", "parent", "current"]. Default value is current
project string[] use this property to filter facet values by project.
additionalType string[] filter facet values by their additional type
campaignTag string[] use this property to filter facet values by campaign tag

Facet scope defintions

Name Description
current standard behavior of Azure Search.Only facets of the current request/response get delivered
all all facets get delivered like if they would be without a selection on the current filter on this facet.
parent facets get delivered like if they would be the parent of the current filter on this facet. Only works with tree facets

there is different responses based on request:

Search Request Body Request type Desscription
{ "facets": null } or { //missing facets } POST, GET Returns all facets
{ "facets": [] } POST With empty array it doesn’t return any facets
{ "facets": [{ "name": "categoryTree" }]} POST Returns only categoryTree facets

Usage of scope in facets

Information

Scope has influence only on the facets values and doesn't have any affect on the search results.

Scope 'Current'

Selection of current scope has the same behavior as if you do not select anything, and values of facet in result will be filtered by all currently applied filters.

body with current scope:

{
  "facets":[
    {
      "name":"addressLocality",
      "scope":"current"
    }
  ],
  "addressLocality":["Chur"]
}

body without any scope:

{
  "facets":[
    {
      "name":"address/addressLocality"
    }
  ],
  "addressLocality":["Chur"]
}

Response (addressLocality facet values) for both request bodies

"address/addressLocality": {
  "filterPropertyName": "addressLocality",
  "values": [
    {
      "facetType": "value",
      "filterType": "object",
      "valueType": "string",
      "value": "Chur",
      "count": 408,
      "query": "Chur",
      "name": "Chur"
    }
  ]
}

Scope 'All'

Selecting of all scope means that for the facet values in results will be applied all selected filters except for the filter with name of facet.

{
  "facets":[
    {
      "name":"addressLocality",
      "scope": "all"
    }
  ],
  "addressLocality":["Chur"]
}

"address/addressLocality": {
  "filterPropertyName": "addressLocality",
  "values": [
    {
        "facetType": "value",
        "filterType": "object",
        "valueType": "string",
        "value": "Zürich",
        "count": 994,
        "query": "Zürich",
        "name": "Zürich"
    },
    {
        "facetType": "value",
        "filterType": "object",
        "valueType": "string",
        "value": "Arosa",
        "count": 590,
        "query": "Arosa",
        "name": "Arosa"
    },
    {
        "facetType": "value",
        "filterType": "object",
        "valueType": "string",
        "value": "Lenzerheide",
        "count": 482,
        "query": "Lenzerheide",
        "name": "Lenzerheide"
    },
    {
        "facetType": "value",
        "filterType": "object",
        "valueType": "string",
        "value": "Chur",
        "count": 408,
        "query": "Chur",
        "name": "Chur"
    },
    ... // other values
  ]
}

Scope 'Parent'

Selecting of parent scope means that for the selected facet instead of provided filters will be applied to their parents.

Attention

Parent scope works only with tree facets (categoryTree, combinedTypeTree)).

Sample: If request has categoryTree facet with scope=parent and categoryTree filter equal to ch_root|ch_01|ch_0615|ch_0101 then values of that facet will be filtered with filter equal ch_root|ch_01|ch_00101.

How filters will be transformed:

  • ch_root|ch_01|ch_0101|ch_010101 -> ch_root|ch_01|ch_0101|
  • ch_root -> filter will be removed
{
    "facets": [
        {
            "name": "categoryTree",
            "count": 100,
            "scope":"parent"
        }
    ],
    "categoryTree":["ch_root|ch_01|ch_0101|ch_010101"]
}

"categoryTree": {
        "filterPropertyName": "categoryTree",
        "values": [
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_10|ch_1009",
                "count": 194,
                "query": "ch_root|ch_10|ch_1009",
                "name": "Ski",
                "namePlural": "Skis"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_01|ch_0105",
                "count": 198,
                "query": "ch_root|ch_01|ch_0105",
                "name": "Winter sports",
                "namePlural": "Winter sports"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_01|ch_0101|ch_010103",
                "count": 255,
                "query": "ch_root|ch_01|ch_0101|ch_010103",
                "name": "Theme Trail",
                "namePlural": "Theme Trails"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_10",
                "count": 259,
                "query": "ch_root|ch_10",
                "name": "Points of Interest",
                "namePlural": "Points of Interests"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_01|ch_0101|ch_010102",
                "count": 370,
                "query": "ch_root|ch_01|ch_0101|ch_010102",
                "name": "Hiking",
                "namePlural": "Hikings"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_01|ch_0101|ch_010108",
                "count": 581,
                "query": "ch_root|ch_01|ch_0101|ch_010108",
                "name": "Wintertrails",
                "namePlural": "Wintertrails"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_01|ch_0101|ch_010104",
                "count": 1209,
                "query": "ch_root|ch_01|ch_0101|ch_010104",
                "name": "Hiking",
                "namePlural": "Hikings"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_01|ch_0101",
                "count": 2409,
                "query": "ch_root|ch_01|ch_0101",
                "name": "Hiking",
                "namePlural": "Hikings"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_01",
                "count": 2409,
                "query": "ch_root|ch_01",
                "name": "Activities",
                "namePlural": "Activities"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root",
                "count": 2409,
                "query": "ch_root",
                "name": "discover.swiss Topics",
                "namePlural": "discover.swiss Topics"
            }
        ]
    }

Warning

Range facets applicable only to facets with int type.

You can get range facets in 2 ways:

  • use values
  • use interval

Get ranges through values

Property values is a string which should be represented in the next format: int|int

Facet values property has next restrictions:

  • values and interval cannot exist at the same time
  • values could contain only int and should be delimited by |, e.g. 10|15|3 - valid, |5|10 - invalid

Here is an example how it could be:

body:

{
  "facets": [
    {
      "name": "ratingCondition",
      "values": "1|2|6"
    }
  ]
}

alternative body:

{
  "facets": [
    {
      "name": "rating/condition",
      "values": "10|25|34"
    }
  ]
} 

{
  "rating/condition": {
    "filterPropertyName": "ratingCondition",
    "values": [{...},{
    "facetType": "range",
    "filterType": "object",
    "valueType": "int",
    "from": 10,
    "to": 25,
    "count": 15,
    "value": null,
    "name": "10 - 25",
    "query": "query:rating/condition gt 10 and rating/condition le 25"
    },{...}]
  }
}

Get ranges through interval

Property interval should be a number

Facet inreval property has the following restrictions:

  • values and interval cannot exist at the same time
  • interval should be int
  • interval should be greater than or equal to 0

Here is an example how it can be:

body:

{
  "facets": [
    {
      "name": "ratingCondition",
      "interval": "2"
    }
  ]
}

{
  "rating/condition": {
    "filterPropertyName": "ratingCondition",
    "values": [{...},{
    "facetType": "range",
    "filterType": "object",
    "valueType": "int",
    "from": 2,
    "to": 4,
    "count": 15,
    "value": null,
    "name": "2 - 4",
    "query": "query:rating/condition gt 2 and rating/condition le 4"
    },{...}]
  }
}

Usage of selectValues

To specify which values do you want to receive in the response you can use selectValues property in the facetRequest.

Warning

It is not possible to use selectValues with filterValues, values or interval at the same time in one facet request.

Sample of the request with 1 facet and 2 values of that facet

body:

{
  "facets": [
    {
      "name": "categoryTree",
      "selectValues": ["ch_root|ch_01", "ch_root|ch_020202"]
    }
  ]
}

Contains only 2 values for categoryTree facet

"facets": {
    "categoryTree": {
        "filterPropertyName": "categoryTree",
        "values": [
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_020202",
                "count": 0,
                "query": "ch_root|ch_020202",
                "name": "Kultur",
                "namePlural": "Kulturs"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "ch_root|ch_01",
                "count": 12229,
                "query": "ch_root|ch_01",
                "name": "Aktivitäten",
                "namePlural": "Aktivitätens"
            }
        ]
    }
}

Usage of filterValues

To filter which values do you want to receive in the response you can use filterValues property in the facetRequest.

Tip

Use cases: show only values of a subtree of the categories or show only a certain type of tags (filter by additionalType using our naming convention (“parking-” filters out all tags about parking)

Sample of the request with 1 facet "tag" and additionalType of that facet which correspond to filter

body:

{
"facets": [
    {
        "name": "tag",   
        "scope": "all",
        "additionalType": ["seasonality"]
    }
 ]
}

Contains all values for additionalType facet

"facets": {
    "tag": {
        "filterPropertyName": "tag",
        "values": [
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "seasonality-summer-only",
                "count": 3,
                "query": "seasonality-summer-only",
                "name": "Nur im Sommer",
                "additionalType": "seasonality"
            },
            {
                "facetType": "value",
                "filterType": "collection",
                "valueType": "string",
                "value": "seasonality-winter-only",
                "count": 20,
                "query": "seasonality-winter-only",
                "name": "Nur im Winter",
                "additionalType": "seasonality"
            }
        ]
    }
}

Warning

It is not possible to use filterValues with selectValues, values or interval at the same time in one facet request.

Sample of the request with 1 facet and values of that facet which correspond to filter

body:

{
  "facets": [
    {
      "name": "categoryTree",
      "filterValues": ["ch_0608", "ch_089456"]
    }
  ]
}

Contains next value for categoryTree facet

"facets": {
  "categoryTree": {
      "filterPropertyName": "categoryTree",
      "values": [
          {
              "facetType": "value",
              "filterType": "collection",
              "valueType": "string",
              "value": "ch_root|ch_06|ch_0608",
              "count": 6,
              "query": "ch_root|ch_06|ch_0608",
              "name": "weitere Kulinarik",
              "namePlural": "weitere Kulinariks"
          }
      ]
  }
}

Usage of projects filters

To filter facets by specific projects you can use project property in the facetRequest.

In case projects can not be asigned to the object type of the facet value, then this filter will be skipped. Currently only containedInPlace/id, tag and categoryTree supports project filter. Therfore to use this filter you must manually assign your project to specific objects (facet values) in the partner portal.

Tip

Use cases: to improve the performance of a search request show only values of containedInPlace/id facet which belong to specific project.

Warning

It is not possible to use project with count at the same time in one facet request. When project is used in facet request then count for that facet is set to int.MaxValue

Filtering by the facet

Filtering by facets is easy with usage of filterPropertyName property from search facet value response and query property from search facet value response.

Warning

Facet name is not applicable for filtering. Only filterPropertyName is appropriate for this purpose. (Wrong: rating/condition, Correct: ratingCondition)

link:

https://api.discover.swiss/info/v2/search?ratingCondition=5&ratingCondition=9

filtering by single query body:

{
  "categoryTree": "query:item eq 'ch_root|ch_01|ch_0102|ch_010208'",
  "ratingCondition":"5"
}
or

{
  "categoryTree": "ch_root|ch_01|ch_0102|ch_010208",
  "ratingCondition": ["5"]
}

or filtering by multiple query of one property body:

{
  "categoryTree": "ch_root|ch_01|ch_0102|ch_010208",
  "ratingCondition":["5", "9"]
}

{
  "count": 15,
  "values": [{...},{...}],
  "facets": {
    "categoryTree": {
      "filterPropertyName": "categoryTree",
      "values": [
        {
          ...
          "query": "ch_root|ch_01|ch_0102|ch_010208"
        }, {...}
      ]
    },  
    "rating/condition" : {
      "filterPropertyName": "ratingCondition",
      "values": [
        {
          ... // other facet value response properties
          "query": "5"
        },
        {
          ... // other facet value response properties
          "query": "9"
        }
      ]
    },
    ... // other facets
  }

Sample of filtering by the facet with 'int' valueType

link:

https://api.discover.swiss/info/v2/search?filters=time eq 50

body:

{
  "filters": "time eq 50"
}

Sample of filtering by the facet with 'string' valueType

link:

https://api.discover.swiss/info/v2/search?filters=address/addressLocality eq 'Martina'

body:

{
  "filters": "address/addressLocality eq 'Martina'"
}

Category tree

You can build a tree from Categories provided in the facets. Property 'value' of each category contains a full parent list separated by '|' from root to the current category.

Sample of categoryTree facet:

 "facets": {
    "categoryTree": {
      "filterPropertyName": "categoryTree",
      "values": [
            {
              "value": "ch_root|ch_01|ch_0101",
              "name": "Wandern"
            },
            ...
      ]
    }
 }

Ordering of facets results

Property facetOrder in search request allows to specify direction for ordering of all facet results in the response by count-numbers within the facet.

link:

https://api.discover.swiss/info/v2/search?facetOrder=desc

body:

{
  "facetOrder": "desc"
}