Map Element

Discover open destinations and see if you can travel.

Embed a travel restrictions map on your web platform using the sherpa SDK.
Don't miss our QuickStart guide.


App Id is required

You will receive a unique APP_ID during onboarding.


You need to include the sherpa° SDK by adding the script tag to the head of your HTML file and include your personalized APP_ID.

You will need to select the appropriate URL and APP_ID depending on whether you are using our Sandbox or Production environment:

<!-- PRODUCTION Envrionment -->
<script src="" defer></script>
<!-- SANDBOX Envrionment -->
<script src="" defer></script>

Embed Map Element

Place an empty div element on your site where you want the Map Element to appear.

<div id="sherpa-map-element"></div>

Use the sherpa° sdk to create an instance of the Map Element object and attach it to the DOM of your site by mounting it to an existing HTML element on your page.

The element.mount accepts a valid CSS Selector.


Always include placement

When embedding the map element for engagement and conversion tracking, include a placement attribute. Without the placement, analytics reports will be limited.

const elementConfig = {
  placement: "discovery"
$sherpa.V2.createElement('map', elementConfig).mount('#sherpa-map-element')

Configure Map Element

The Map Element can also be customized through an optional configuration object.

const elementConfig = {
  trip: {
    originAirport: 'JFK',
    destinationAirport: 'MUC',
  travellers: [
      nationality: 'CAN',
      vaccinations: [
          type: 'COVID_19',
          status: 'FULLY_VACCINATED',
  placement: 'destinationPage',
  features: {
    showFilters: true,
    showMapLegend: true,
  queryParams: {
    utm_source: 'email',
    utm_medium: 'newsletter',
    utm_campaign: 'summer-return-to-travel'

$sherpa.V2.createElement('map', elementConfig).mount('#sherpa-map')


No Element Div Passed

Please note if no div element is passed the browser will automatically create a container at the next available space.


Multiple Element Divs

If multiple div containers are created please ensure the correct container name is passed for the mount statement.

Options for a Map Element


Origin and Destination for a Round Trip

The Map Element provides detailed information as a Round Trip, going from A to B and returning to A. Both origin and destination can be provided as options to the Map Element by setting *either the country, region or airport.

E.g. if originAirport is provided, both originCountry and originRegion do not have to be provided again.

options propertytypedescription
languagestringdefault: en-US
View supported languages
placementstringName of booking stage or page the element is embedded on. Used for measuring engagement in analytics reports.
Suggested values in camelCase:
homePage - Home Page
discovery - Generic pre-booking marketing page
mmb - Manage My Booking
search - Search
bookingConfirmation - Booking Confirmation
destinationPage - dedicated marketing page for a destination
covidPage - dedicated page for COVID-19 resources
defaultNationalityStringISO3 Country Code, e.g. CAN for Canada
or browser to determine nationality based on the language settings of the browser.
tripObjectView Trip Model
travellersArray of ObjectsView Traveller Model
queryParamsobjectView Analytics Model
featuresObjectView Features Model

Trip Model

originCountryRequiredStringalpha2 or alpha3 country code, e.g. CA or CAN for Canada
originRegionOptionalStringalpha3 region code e.g. US-TX for Texas, USA
originAirportOptionalStringIATA Airport Code e.g. YYZ for Pearson International Airport, Toronto, Canada
destinationCountryOptionalStringalpha2 or alpha3 country code, e.g. CA or CAN for Canada
destinationRegionOptionalStringalpha3 region code e.g. US-TX for Texas, USA
destinationAirportOptionalStringIATA Airport Code e.g. YYZ for Pearson International Airport, Toronto, Canada

Traveller Model

nationalityOptionalStringISO3 Country Code
, e.g. CAN for Canada
vaccinationsOptionalArray of ObjectsView Vaccination Model

The first element of the travellers array is used to populate the passport and vaccine filters (if shown by setting features.showFilters to true).
The value of nationality attribute, if it is present, will be used as the default value of the passport filter. If the first element of the travellers array doesn't have a nationality attribute or there is no travellers array in the options, the passport filter will default to the value specified in defaultNationality.
The status value of the vaccinations attribute, if it is present, will be used to set the default value of the "COVID-19 vaccinated" toggle (FULLY_VACCINATED = "Yes", NOT_VACCINATED = "No). If the first element of the travellers array doesn't have a vaccinations attribute or there is no travellers array in the options, the "COVID-19 vaccinated" toggle will default to "No".

Vaccination Model

typeOptionalStringCurrently only value 'COVID_19'
Indication of being fully vaccinated or not

Analytics Model

Pass analytics attributes to the segment element. The parameters will be appended to the iFrame url where the Map Element is rendered, and appear in your reports.

utm_sourceOptionalStringUTM source. Example: email
utm_mediumOptionalStringUTM medium. Example: newsletter
utm_campaignOptionalStringUTM campaign. Example: summer-return-to-travel

Features Model

Customize the appearance of the Map Element by enabling and disabling feature flags.

showFiltersOptionalBooleanShow/hide filters above the map.
showMapLegendOptionalBooleanShow/hide map legend below the map.

Custom iFrame integration

The Map Element can also be integrated through a custom iFrame rather than utilizing the dynamic sherpa° SDK. This might be useful if the Map Element needs to be embedded into a Content Management System that is not flexible, or to using the Map Element in a WebView for mobile experiences.


Fixed iFrame dimensions required

Our Embedded Elements are fully responsive and adjust to fill out 100% of the available width. The height is automatically adjusted if you are using the sherpa° SDK. Choosing a custom iFrame integration means that you take on the responsibility to ensure that enough height is provided to the the Element to display correctly. The default height for the Map Element is set to 500px.

Url format

Configuration options

The sherpa° SDK provides optional parameters to specify your itinerary and additional features. These options have to be constructed manually using query parameters.

// Setting the origin to a country e.g. Canada

// Setting the origin to an airport e.g. Pearson Airport, Toronto, Canada

// Setting the default view to fullscreen