Settings

Search engine ID (required).

This ID can be found at account/settings after you have created a search engine for your account.

Template for widget search link URLs.

It is strongly recommended to provide this, unless you are setting a handleSearchClick function instead.

This template must contain a {searchTerms} tag, and may contain {mediaThumbBar}, {searchSuggestions}, and {wordToDefine} tags.

Example: /?q={searchTerms}

Click handler for the internal search links in widgets.

Used where new search results are loaded dynamically (using JavaScript) rather than via traditional page navigation, meaning that searchUrlTemplate alone is insufficient. If set, search links will not be followed and this function will handle the click instead.

See Search Links page for details.

The current search query.

If unset, Search Expander will attempt to get the value from a search input (see searchInput) or the current URL.

Search input with q value.

Alternatively, set a data-sxpr-input HTML attribute on the input (or add q setting).

Array of the current search results, in the form of objects with a url and title property.

Alternatively, add a data-sxpr-link attribute to each of your search result links, or set a links property.

Iterable containing search result link elements, or a selector string for obtaining them.

(This is an alternative to results and data-sxpr-link attributes.)

HTML container for knowledge panel widget, or a selector string for obtaining it.

Alternatively, set a data-sxpr-knowledge-panel HTML attribute on the container.

HTML container for media thumbnail bar widget, or a selector string for obtaining it.

Alternatively, set a data-sxpr-media-thumb-bar HTML attribute on the container.

HTML container for instant answers widget, or a selector string for obtaining it.

Alternatively, set a data-sxpr-instant-answers HTML attribute on the container.

HTML container for top bar, or a selector string for obtaining it.

Alternatively, set a data-sxpr-top-bar HTML attribute on the container.

HTML container for shopping results, or a selector string for obtaining it.

Alternatively, set a data-sxpr-shopping HTML attribute on the container.

Two-letter ISO 639-1 language code, used to get results in a particular language.

Currently supported languages are en, de, es, fr, it, nl.

Search Expander will attempt to derive lang from browser settings unless this value is explicitly set.

Two-letter country code, used to specify the end user market.

This setting is normally detected automatically from browser settings, but can be specified explicitly if desired.

An object containing data about the end user's geographical location, specified as city, state, country, lat (latitude) and lng (longitude).

This data is used by the Instant Answers widgets, e.g. the weather widget. Each of the object's properties is optional.

lat and lng must be specified as numbers (decimal degrees).

A broad category of user agent for analytics purposes. One of:

• 'desktop'
• 'tablet'
• 'phone'
• 'ios_app_phone'
• 'ios_app_tablet'
• 'android_app_phone'
• 'android_app_tablet'
• 'firefox_extension'
• 'chrome_extension'
• 'edge_extension'

Style settings for customising the appearance of widgets.

Example: { foreground: '#222' }

See Styling page for the available style settings.

Whether to show loading bars in widgets while they load. Set to true to enable all, false to disable all, and 'blank' to take up visual space during loading without showing loading bars.

Individual widget containers can be enabled, disabled or set to 'blank', e.g. {knowledgePanel: false, instantAnswers: 'blank'}.

Specific types of widget can be targeted individually using objects nested inside some containers, e.g. {instantAnswers: {calc: false, dict: 'blank'}, topBar: {searchSuggestions: true}}.

Most widgets default to true.

The minimum viewport width (px) at which desktop-oriented styles are active for the various instant answers widgets. Allowed properties: calc, dict, moviesAndTV, smartAnswers, timezone, weather, youtube.

Example: { calc: 768, weather: 1024 }

The minimum viewport width (px) at which desktop-oriented styles are active for the shopping widget.

Array of knowledge panel tab IDs to enable.

Tab IDs:

• overview
• summary
• actorCredits
• albums
• albumTracks
• artistSimilar
• authorBooks
• bookAuthorBooks
• bookSimilar
• cast
• movieTvSimilar
• trailers
• tvEpisodes
• songs
• streaming
• videoGameFranchiseGames
• videoGameSimilar
• videoGameVideos

(Default all tabs enabled.)

Choose between a Here Maps embed, a Google Maps embed, or no map, for Tripadvisor Knowledge Panels and Tripadvisor Places Instant Answers.

When using heremaps, a hereMapsApiKey must be provided. For Tripadvisor Knowledge Panels, Here Maps static images will be served using your hereMapsApiKey. For Tripadvisor Places Instant Answers, Here Maps vector tiles will be served using your hereMapsApiKey.

When using tomtom, a tomTomStyleUrl and tomTomApiKey must be provided. For Tripadvisor Knowledge Panels, static images will be served using your tomTomApiKey. For Tripadvisor Places Instant Answers, TomTom interactive maps will be served using your tomTomStyleUrl.

(Default heremaps.)

We recommend you whitelist your domain name within the settings page of your map provider (e.g. Here Maps, TomTom) and activate the setting to disable any requests from any other domains. The API key provided to the Search Expander library will be publicly exposed, so doing this will prevent any unauthorised use of your API key.

Overrides tripadvisorMap setting for Tripadvisor Properties knowledge panels.

Overrides tripadvisorMap setting for Tripadvisor Places Instant Answers widgets.

Set the static map to link to a map page for the property. This can be a link to Tripadvisor, Google Maps, a custom map page, or none for no link. (Default google.)

Note that if custom is selected, a URL template must be provided via the setting tripadvisorMapLinkUrlTemplate.

Template for static map image custom link URLs in Tripadvisor panels and Tripadvisor Places Instant Answers widgets.

This template must contain a {searchTerms} tag, which will be populated with a search query.

Example: https://example.com/?q={searchTerms}

Whether the map embed should have zoom/drag capability.

Requires tripadvisorMap, tripadvisorPropertiesMap or tripadvisorPlacesMap to be set to 'heremaps' and hereMapsApiKey to be set to a valid API key.

(Default false.)

Whether the map embed should have a menu for satellite/traffic layers.

Requires tripadvisorMap, tripadvisorPropertiesMap or tripadvisorPlacesMap to be set to 'heremaps' and hereMapsApiKey to be set to a valid API key.

This setting is incompatible with the hereMapsProxy setting.

(Default false.)

This function will be called whenever a Tripadvisor Places map is ready to load. If set, any default map settings are ignored and this function is expected to handle custom map rendering. It is passed an object containing the following data:

container: HTMLElement;
properties: {
	lat: number | null;
	lng: number | null;
	name: string;
	id: number;
	visible: boolean;
}[]

container is the HTML element in which the map is normally rendered. properties is an array of objects specifying each location.

The function should return false if there was an error and the map could not be rendered.

This function will be called whenever a Tripadvisor Places widget expands to include more locations on the map and property list (see tripadvisorPlacesExpand). It is passed the same argument as handleTripadvisorMap.

Your own Here Maps API key. If not set, Here Maps map embeds and images will be disabled.

Our Tripadvisor Places Instant Answers widget uses Here Maps vector map tiles, while our Tripadvisor Knowledge Panel uses Here Maps static map images. The API key you specify here will be used to retrieve both.

We recommend you whitelist your domain name within the settings page of your map provider (e.g. Here Maps, TomTom) and activate the setting to disable any requests from any other domains. The API key provided to the Search Expander library will be publicly exposed, so doing this will prevent any unauthorised use of your API key.

This object can be used to configure proxy settings for Here Maps, if they are used in the Tripadvisor Places IA widget. To proxy requests to Here Maps, you must specify two domains, optionally adding paths, subdomains and protocols.

js.domain must be a domain (with optional path) for a proxy forwarding requests to https://js.api.here.com.

vector.domain must be a domain (with optional path) for a proxy forwarding requests to https://vector.hereapi.com.

{
    js: {
        domain: 'example.com/proxy/js',
        protocol: 'https',    // optional
        subdomain: null,      // optional
    },
    vector: {
        domain: 'example.com/proxy/vector',
        protocol: 'http',     // optional
        subdomain: 'example', // optional
    }
}

Your own TomTom API key. If not set, TomTom static map images will be disabled.

We recommend you whitelist your domain name within the settings page of your map provider (e.g. Here Maps, TomTom) and activate the setting to disable any requests from any other domains. The API key provided to the Search Expander library will be publicly exposed, so doing this will prevent any unauthorised use of your API key.

A URL to a TomTom map style JSON file, associated with your TomTom account. (See mapmaker.tomtom.com.) If not set, TomTom interactive maps will be disabled.

To offer different map styles, you can provide an object mapping option labels to style URLs, e.g.:

{
    default: {
        light: 'https://example.com/default-light.json',
        dark: 'https://example.com/default-dark.json',
    },
    'Satellite view': 'https://example.com/satellite.json',
    'Traffic view': {
        light: 'https://example.com/traffic-light.json',
        dark: 'https://example.com/traffic-dark.json',
    },
}

In this object, the key default must be set, and other keys must be labels for options in a select menu. Values must be either URLs or an object specifying a light and dark URL. (See styles.tripadvisor.mapColorMode.)

We recommend you whitelist your domain name within the settings page of your map provider (e.g. Here Maps, TomTom) and activate the setting to disable any requests from any other domains. The API key provided to the Search Expander library will be publicly exposed, so doing this will prevent any unauthorised use of your API key.

URL template for proxying requests to the TomTom API when using TomTom map embeds.

Note that this template is for map tile requests, and is not applied to the style JSON URL(s) you provide to the tomTomStyleUrl setting.

Example: https://example.com/proxy?url={url}

Whether to add a prompt for the user to enter their location data for the purposes of Tripadvisor-related queries. The prompt will be part of the Tripadvisor Places IA widget. Default true.

Note: This feature makes use of the Geolocation web API, which will cause the user's browser to ask them for permission to access their location data. The data is stored client-side in localStorage and overrides any user location data set explicitly in the sxpr settings object.

The allowLocalStorage or allowLocalStorage.allowLocationStorage setting must be true to allow the user location widget to appear.

Privacy policy page URL for the map location widget.

This setting enables product ads in either the top bar as a carousel or in the knowledge panel.

Set to true or 'topBar' to enable product ads in a top bar carousel, or to 'knowledgePanel' to enable product ads in a section of the knowledge panel, or false to disable. (Default false.)

If true, all widgets apart from shopping widgets will be disabled and requests will not be billable. Default false.

This setting overrides the above settings for enabling widgets.

URL template for proxying requests to the Search Expander API.

Example: /api-proxy?path={path}

Example: https://proxy.example.com{path}

See the documentation for more details.

URL template for proxying requests for Search Expander assets such as CSS and JavaScript files.

Example: /assets-proxy?path={path}

Example: https://example.com/assets-proxy?url={url}

Example: https://proxy.example.com{path}

URL template for proxying image requests made by Search Expander widgets.

Example: https://example.com/proxy?url={url}

URL template for proxying requests for third-party audio in Search Expander widgets.

Example: https://example.com/proxy?url={url}

URL template for proxying requests to the Wikipedia API in Search Expander widgets (for snippet popups).

Example: https://example.com/proxy?url={url}

URL template for proxying requests to the TomTom API when using TomTom map embeds.

Note that this template is for map tile requests, and is not applied to the style JSON URL(s) you provide to the tomTomStyleUrl setting.

Example: https://example.com/proxy?url={url}

If imageUrlTemplate is set, you can exclude certain domains from being filtered by this template by adding them to this setting.

Example: ['wikimedia.org']

If audioUrlTemplate is set, you can exclude certain domains from being filtered by this template by adding them to this setting.

Example: ['wikimedia.org']

ID used to trigger a relevant media thumbnail bar.

Normally this value will be automatically picked up via URL data, but where this is not possible you can set it manually.

(Alternatively, add the value to a hidden input with the name sx-media-thumb-bar.)

ID used to trigger a relevant search suggestions bar.

Normally this value will be automatically picked up via URL data, but where this is not possible you can set it manually.

(Alternatively, add the value to a hidden input with the name sx-search-suggestions.)

Word to define using the dictionary instant answers widget.

Normally this value will be picked up via URL data, but where this is not possible you can set it manually.

(Alternatively, add the value to a hidden input with the name sx-word-to-define.)

Template for shopping route link URLs. These links will appear in widgets and navigate users to your shopping route.

This template should be passed to both sxpr() and sxpr.shopping().

It is strongly recommended that you provide this setting, unless you are using a handleShoppingClick function instead.

Example: https://example.com/shopping/?q={searchTerms}

Click handler for the internal shopping route links in widgets.

Used where new shopping results are loaded dynamically (using JavaScript) rather than via traditional page navigation, meaning that shoppingUrlTemplate alone is insufficient. If set, shopping route links will not be followed and this function will handle the click instead.

More info

Whether to automatically scroll the viewport to the top of the shopping widget after product thumbnails have been loaded.

Default small (i.e. auto-scrolling behaviour applies to small viewports only).

Whether to add a carousel of sponsored product thumbs across the top of the shopping widget. (Default true.)

Whether to add a carousel of eco-friendly product thumbs across the top of the shopping widget. (Default false.)

Whether to prioritise Kelkoo product ads or Yadore product ads where they appear on your web SERP. (Default kelkoo.)

Whether to allow adult product ads in the web SERP shopping widgets. (Default true.)

Note that if safeSearch is true (the default), this setting is overridden and adult product ads are not allowed on the web SERP.

Whether to allow adult product ads in the shopping widget. (Default true.)

Note that if safeSearch is true (the default), this setting is overridden and adult product ads are not allowed in the shopping widget.

Whether to add a new browser history entry when the user updates the shopping widget filter parameters. This allows for URL sharing and bookmarking of particular shopping results. (Default true.)

Note that a valid URL template must be provided for the shoppingUrlTemplate setting, e.g. https://example.com/shop/?q={searchTerms}.

Set to true to allow storage of a small amount of client-side data in localStorage. This can improve user experience, including increasing request speed. This is never used for tracking or personal data collection. No cookies are set or read by Search Expander.

To opt in to specific uses of localStorage, specify an object instead of a boolean and specify a boolean for one or more of:

• allowSuccessFlagStorage: Used for improved front-end performance
• allowMarketCodeStorage: User market is used for analytics and product ads (where these are opted into). You can set a market value explicitly to eliminate the need for this.
• allowLocationStorage: Used where user location is useful for serving relevant data, including Tripadvisor maps and weather data. User location data is approximate.

Default false.