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[]
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[]
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

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 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 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)
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

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 have influence only on the facets values, and doesn't have any affect on the search results.

Scope 'Current'

Selection of current scope have 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 of 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 ds_root|ds_06|ds_0615|ds_061501 then values of that facet will be filtered with filter equal ds_root|ds_06|ds_0615.

How filters will be transformed:

  • ds_root|ds_06|ds_0615|ds_061501 -> ds_root|ds_06|ds_0615
  • ds_root -> filter will be removed
{
    "facets": [
        {
            "name": "categoryTree",
            "count": 100,
            "scope":"parent"
        }
    ],
    "categoryTree":["ds_root|ds_06|ds_0615|ds_061501"]
}
"categoryTree": {
  "filterPropertyName": "categoryTree",
  "values": [
    {
      "facetType": "value",
      "filterType": "collection",
      "valueType": "string",
      "value": "ds_root",
      "count": 168,
      "query": "ds_root",
      "name": "discover.swiss category",
      "namePlural": "discover.swiss categories"
    },
    {
      "facetType": "value",
      "filterType": "collection",
      "valueType": "string",
      "value": "ds_root|ds_06",
      "count": 168,
      "query": "ds_root|ds_06",
      "name": "Unterkünfte",
      "namePlural": "Unterkünftes"
    },
    {
      "facetType": "value",
      "filterType": "collection",
      "valueType": "string",
      "value": "ds_root|ds_06|ds_0615",
      "count": 168,
      "query": "ds_root|ds_06|ds_0615",
      "name": "Hütte",
      "namePlural": "Hüttes"
    },
    {
      "facetType": "value",
      "filterType": "collection",
      "valueType": "string",
      "value": "ds_root|ds_06|ds_0615|ds_061501",
      "count": 146,
      "query": "ds_root|ds_06|ds_0615|ds_061501",
      "name": "Mountain hut",
      "namePlural": "Mountain huts"
    }
  ]
}

Usage of range and interval in facets

You can get facets grouped by the range of numbers.

For example range of rating conditions:

{
  "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"
      },{...}]
  }
}

Warning

Range facets applicable only to facets with int type.

You can get range facets by 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 in the same time
  • values could contain only int and should be delimited by |, e.g. 10|15|3 - valid, |5|10 - invalid

Here is 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 in the same time
  • interval should be int
  • interval should be greater than or equal to 0

Here is 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

Usage of filterValues

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

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"
          }
      ]
  }
}

body:

{
  "facets": [
    {
      "name": "categoryTree",
      "selectValues": ["ds_root|ds_06", "ds_root|ds_089456"]
    }
  ]
}

Contains only 2 values for categoryTree facet

"facets": {
  "categoryTree": {
      "filterPropertyName": "categoryTree",
      "values": [
          {
              ...
              "value": "ds_root|ds_06",
              "count": 2171,
              ...
          },
          {
              ...
              "value": "ds_root|ds_089456",
              "count": 0,
              ...
          }
      ]
  }
}

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 'ds_root|ds_01|ds_0102|ds_010208'",
  "ratingCondition":"5"
}
or

{
  "categoryTree": "ds_root|ds_01|ds_0102|ds_010208",
  "ratingCondition": ["5"]
}

or filtering by multiple query of one property body:

{
  "categoryTree": "ds_root|ds_01|ds_0102|ds_010208",
  "ratingCondition":["5", "9"]
}
{
  "count": 15,
  "values": [{...},{...}],
  "facets": {
    "categoryTree": {
      "filterPropertyName": "categoryTree",
      "values": [
        {
          ...
          "query": "ds_root|ds_01|ds_0102|ds_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 full parent list separated by '|' from root to current category.

Sample of categoryTree facet:

 "facets": {
    "categoryTree": {
      "filterPropertyName": "categoryTree",
      "values": [
            {
              "value": "ds_root|ds_01|ds_0101",
              "name": "Wandern"
            },
            ...
      ]
    }
 }

Last update: February 25, 2021 11:51:22