Skip to content

Search api overview

Search api as part of the Infocenter is designed to speed up database searches. We are using Azure Cognitive 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.

Custom filter properties

Parameter Type Description
datasource string[] Optional. Determines one or many datasources used to filter data
project string[] Optional. Determines one or many projects used to filter data
category string[] Optional. Determines one or many categories used to filter data
campaignTag string[] Optional. Determines one or many campaign tag by which data will be filtered
profileTag string[] Optional. Determines one or many profile tag by which data will be filtered

Facets filter properies

For filtering by facets it is necessary to use porerty 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[]
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

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 Retrive 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 + +
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 + + + +
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[] + +
link Link[] +
recurredCount int + +
nextOccurrence dateTimeOffset + +
availableDataLanguage string[] +
created dateTime +
lastModified dateTime + +

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.

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

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.

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

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
    },
    ...

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.

Warning

Only one of the two scoring parameters (scoringReferencePoint, scoringTags) can be used in the same time.

How to use

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.

Warning

Only one of the two scoring parameters (scoringReferencePoint, scoringTags) can be used in the same time.

How to use

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

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.


Last update: June 7, 2021 09:00:29