Search api overview

Search api as part of the Infocenter is designed to speed up database searches. We are using Azure Cognitive Search

Base url for search

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

There are GET and POST endpoints for search.

Sample application

You can see search in sample application: demo.discover.swiss/search

Search request

Parameter	Type	Description
searchText	string	Optional. Search for contained string by the searchable fields
searchFields	string	Optional. When name of fields are specified as a comma separated string (e.g. "name, description, address/name") then only the selected fields will be used for searching.
select	string	Optional. When name of fields are specified as a comma separated string (e.g. "name, description, @id, address") then only the selected fields will be returned.
filters	string[]	Optional. Odata strings for filters
currentPage	int	Optional. By default equal 1. Determines which page of results to return in the response. Note: see limitations below the table
resultsPerPage	int	Optional. By default equal 10 for regular request and 50 for pdf request. Determines how many results are in response
orderBy	string	Optional. Determines name of field by which result will be ordered
facets	FacetRequest[]	Optional. List of facets which will be in the response
scoringTags	string[]	Optional. List of tags which will be used for scoring (Beta) of results in the response
scoringReferencePoint	string	Optional. Coordinates of point in format 'Longitude,Latitude' (e.g.: 8.5172912,47.5722339) which will be used for scoring by distance

Warning

There is a limitation for currentPage parameter - the product of the currentPage and resultsPerPage parameters must not exceed 100000

Information

If resultsPerPage less than 1 then default value will be applied.

Tip

For pagination better use orderBy parameter to avoid duplicates in the result. For example order by identifier.

Custom filter properties

Parameter	Type	Description
datasource	string[]	Optional. List of datasources to filter by (with OR condition).
project	string[]	Optional. List of projects to filter by (with OR condition).
sourcePartner	string[]	Optional. List of source partners acronyms to filter by (with OR condition).
sourceId	string[]	Optional. List of source ids to filter by (with OR condition).
category	string[]	Optional. List of categories to filter by (with OR condition).
allTag	string[]	Optional. List of tags to filter by (with OR condition).
profileTag	string[]	Optional. List of profile tags to filter by (with OR condition).
campaignTag	string[]	Optional. List of campaign tags to filter by (with OR condition).
location	string[]	Optional. List of location ids to filter by (with OR condition).
award	string[]	Optional. List of award ids to filter by (with OR condition).
action	string[]	Optional. List of action to filter by (with OR condition). Possible values: OrderActionWeb, RegisterActionWeb and OrderActionDsMarket.

Facets filter properties

For filtering by facets it is necessary to use property filterPropertyName from Search facet response as a request property name. These filter properties are optional.

List of available facets filters

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

Localization

Default value

de-CH

Language: Based on the Accept-Language header localized properties are translated. Search language is based on this header as well (e.g. for de-CH it will search only in german translations if the translation is available for this porperty.

Search response

Any search response contains list of possible filters and total number of results matching current query.

Property name	Type	Description
count	int (nullable)	actual count of results in actual query but not count possible results
values	SearchValueResponse[]	paged count of results by query
facets	{string, SearchFacetResponse}[]	Dictionary of facets by the query. Where the key is a string with name of facets from azure search, and the value is SearchFacetResponse

Search index definition

Property name	Type	Retrieve	Search	Filter	Facet	Sort
datasource	string[]	+		+
project	string[]			+
type	string	+		+		+
combinedType	string[]			+	+
combinedTypeTree	string[]			+	+
leafType	string		+	+	+
additionalType	string	+				+
identifier	string	+
@id	string	+
address(/addressLocality)	object(string)	+		+	+
address/postalCode	object(string)	+		+	+
address/(name/{de/en/fr/it})	object(string)	+	+
address/addressLine	object(string)	+	+
address/streetAddress	object(string)	+	+
geo	GeographyPoint	+		+
geoDestination	GeographyPoint	+		+
name/{de/en/fr/it}	string	+	+			+
description/{de/en/fr/it}	string		+
disambiguatingDescription/{de/en/fr/it}	string	+	+
openingHours	string	+	+
schedule(/byDay)	object	+		+
schedule(/startDate)	object	+		+
schedule(/endDate)	object	+		+
schedule(/startTime)	object	+		+
schedule(/endTime)	object	+		+
image	ImageObject	+
tag	string[]			+	+
campaignTag	string[]	+		+	+
profileTag	string[]			+
allTag	string[]			+
category	string[]	+		+
categoryTree	string[]			+	+
containedInPlace(/id)	object			+	+
dataGovernance	DataGovernance	+
ouaId	int	+
time	int	+		+	+	+
length	double	+		+	+
state	string	+		+	+
rating(/condition)	object(int)	+		+	+
rating(/difficulty)	object(int)	+		+	+
elevation(/ascent)	object(int)	+		+	+	+
elevation(/descent)	object(int)	+		+	+
elevation(/minAltitude)	object(int)	+		+	+
elevation(/maxAltitude)	object(int)	+		+	+
season	string[]			+	+
sourcePartner	string[]			+	+
link	Link[]	+
recurredCount	int	+				+
nextOccurrence	dateTimeOffset	+				+
availableDataLanguage	string[]			+
created	dateTime					+
lastModified	dateTime	+		+
hasReview	string	+		+
location	string	+		+
award	string	+		+
action	string[]			+	+

Warning

{de/en/fr/it} - means that this property is available on the different languages

Information

Type definition object(string) for properties like address(/addressLocality) means that type of address is object and type of /addressLocality property is string.

Information

The description in the response is obsolete and not officially retrievable anymore. it is only retrievable out of backward compatibility and contains the disambiguatingDescription.

Searching

There is a possibility to use text search in search api.
Read more about searching here

Filtering

Search api supports filtering by exact fields of the search model.
Read more about filtering here

Filtering by availability

For configured productsm the search api supports filtering by availability.
Read more about filtering by availability here

Facets

There are facets in response which can be used for filtering and more.
Read more about facets here

Selecting of fields for result

It is possible to specify which fields should be returned in the response. Read more about selecting fields here

Event ordering

Search definition contains 2 properties to simplify event order experience.
These properties are:

• nextOccurrence - contains the date and time of the next occurrence of event.
• recurredCount - contains the number of repetitions of the event with one week frequency.

When it is necessary to move single-repetition events to the top of results, and simultaneously order all events by date, it is easy to use the search request parameter orderBy and order by properties mentioned above.

Sample of events ordering

Order by date first and then by repetition number.

Request(POST)Response

link:

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

body:

{
    "select": "nextOccurrence,recurredCount",
    "orderBy": "nextOccurrence asc, recurredCount asc"
}

"values": [
    {
        "nextOccurrence": "2021-03-22T13:00:00+00:00",
        "recurredCount": 4151
    },
    {
        "nextOccurrence": "2021-03-22T13:30:00+00:00",
        "recurredCount": 17
    },
    {
        "nextOccurrence": "2021-03-22T14:00:00+00:00",
        "recurredCount": 9
    },
    {
        "nextOccurrence": "2021-03-22T14:00:00+00:00",
        "recurredCount": 17
    },
    {
        "nextOccurrence": "2021-03-22T14:00:00+00:00",
        "recurredCount": 18
    },

Order by repetition number first and then by date

Request(POST)Response

link:

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

body:

{
    "select": "nextOccurrence,recurredCount",
    "orderBy": "recurredCount asc, nextOccurrence asc"
}

"values": [
    {
        "nextOccurrence": "2021-03-23T08:00:00+00:00",
        "recurredCount": 1
    },
    {
        "nextOccurrence": "2021-03-23T10:00:00+00:00",
        "recurredCount": 1
    },
    {
        "nextOccurrence": "2021-03-23T13:00:00+00:00",
        "recurredCount": 1
    },
    {
        "nextOccurrence": "2021-03-23T15:00:00+00:00",
        "recurredCount": 1
    },
    {
        "nextOccurrence": "2021-03-24T00:00:00+00:00",
        "recurredCount": 1
    },
    ...

Order by name alphabetically and ascending

Request(POST)Response

link:

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

body:

{
    "select": "identifier,type,name",
    "orderBy": "name/en asc",
}

"values": [
    {
        "identifier": "eve_wt1_idgddhadi",
        "type": "Event",
        "name": "47. SIMM - Swiss International Mountain Marathon 2022"
    },
    {
        "identifier": "eve_wt1_icacecidi",
        "type": "Event",
        "name": "ACLA: Texturen von Marcus Maeder in Tenna"
    },
    {
        "identifier": "eve_wt1_hbddgchfi",
        "type": "Event",
        "name": "Animals dalla muntogna in Brigels"
    },
    {
        "identifier": "eve_wt1_icfhchiai",
        "type": "Event",
        "name": "Après-Ski mit DJ Mags in Brigels"
    },
    {
        "identifier": "eve_wt1_hcbhjfgbd",
        "type": "Event",
        "name": "Bike Marathon Lumnezia"
    }
    ...

Potential action filtering

For filtering by potentialAction use action filter. Possible filter values

1. OrderActionWeb. Object has booking link.
2. OrderActionDsMarket. Object is bookable via discover.swiss.
3. RegisterActionWeb. Object has registration link.

There are 2 filtering options: directly use the action property or use the filters property.

Request (POST)Response

{
    "select": "identifier,type,potentialAction",
    "action": ["OrderActionWeb"]
}

or

{
    "select": "identifier,type,potentialAction",
    "filters": ["action/any(a: a eq 'OrderActionWeb')"]
}

{
  "identifier": "tom_tds00020012422399480",
  "type": "Product",
  "potentialAction": [
  {
    "additionalType": "OrderAction",
    "target": [
    {
      "type": "Web",
      "urlTemplate": "https://tours.zuerich.com/Zurich/experience/detail/TDS00020012422399480?globalReset=1"
    }
    ],
    "name": "Zürich Tourismus"
  },
  {
    "additionalType": "OrderAction",
    "target": [
    {
      "type": "DsMarket",
      "additionalType": "Offers"
    },
    {
      "type": "DsMarket",
      "additionalType": "Availability"
    }
    ]
  }
  ]
}

Personalization scoring (Beta)

It is available to prioritize results of the search by profile tags using scoringTags request parameter.

When scoringTags have values in the request, all values in response with profile tags equal to values from scoringTags will be moved to the top of search results.

How to use

GetPost

link:

https://api.discover.swiss/info/v2/search?scoringTags=profile-sport-1&scoringTags=profile-sport-3

link:

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

body:

{
    "scoringTags": ["profile-sport-1", "profile-sport-3"]
}

Distance scoring

It is available to prioritize results of the search by distance between selected point and geo property of result objects using scoringReferencePoint request parameter.

Information

Ordering of result from the nearest point to the farthest is applied only for objects distance to which, from selected point, are less then 100km.

How to use

GetPost

link:

https://api.discover.swiss/info/v2/search?scoringReferencePoint=8.5172912,47.5722339

link:

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

body:

{
    "scoringReferencePoint": "8.5172912,47.5722339"
}

How to get results in PDF

It is possible to get pdf with any regular search request. For that it is necessary to use a special endpoint: /search/pdf/{project}/{template}

How to use

GetPost

link:

https://api.discover.swiss/info/v2/search/pdf/grf-vt/search?Type=Event

link:

https://api.discover.swiss/info/v2/search/pdf/grf-vt/search

body:

{
    "type": ["Event"]
}

Read more about pdf result here.