Developer docs

This documentation is meant to help you create multiple Stay22 maps you can use for all and any of your pages. With just a location and a starting date, you’re able to instantly generate an infinite amount of Stay22 maps and integrate them onto your app/website. Find below all the information needed to get you started. Last updated: Sep 24th 2020

If you’re interested in creating one single map for one event, you can create a map using our self-serve service.

Quickstart integration guide using <script>

This script below is all you need to generate a map. Simply copy paste the below script anywhere in your body tag where you want the map to be shown. Then, fill out the 3 required steps (affiliate id, location, and dates) in the code.

<script id="stay22-script">
document.addEventListener("DOMContentLoaded", function(e) {
    // 1. Edit widget size
    var settings22 = {
        width:  '100%', // set the width in px or %
        height: '460px' // set the height in px or %
    };

    // 2. Fill out your config here and the rest should work (customize with more parameters at the end of the docs)
    var s22obj = {
        aid:       'affiliateid',                    // 1) your affiliate id for tracking
        address:   'Madison Square Park, New York' , // 2) Lat/Lng or full street address. For latlng use the "lat":,"lng": keys instead
        checkin:   '2020-08-22',                     // 3) checkin date for their stay in MM/DD/YYYY or ISO 8601 format
        maincolor: '00549E'                          // your main brand color in hex (without the #)
    };

    // Leave this part as-is; it inserts the map iframe on your page
    var params22=''; for (var key in s22obj){if (params22){params22 +='&';}params22 +=key + '=' + encodeURIComponent(s22obj[key]);}var div22=document.getElementById('stay22-script'); div22.insertAdjacentHTML('afterend', '<iframe id="stay22-widget" width="' + settings22.width + '" height="' + settings22.height + '" src="' + 'https://www.stay22.com/embed/gm?' + params22 + '" frameborder="0"></iframe>');
});
</script>

Advanced: Manual integration guide using <iframe>

To have more flexibility, we recommend using this method of integration. The iframe integration is the most common implementation through all Stay22 partners as it can be easily customized. Everything is built upon a single URL. You will require this URL to start and will be able to add parameters along the way.

iframe code:

<iframe src="https://www.stay22.com/embed/gm?aid=5f43af434354585465998a65&lat=40.742612&lng=-73.987777" id="stay22-widget" width="100%" height="460" frameborder="0"></iframe>

The code above will generate this map:

Required URL parameters:

In order for a map to be generated fully, it requires 3 parameters: affiliate ID, location, and date. Find more details below on how to integrate the required parameters.

1) Affiliate ID

Having an affiliate ID will help you track clicks, loads, and earnings. Login to your dashboard to find out what it is if unsure. We recommend the aid parameter to be the first parameter in the URL so we can detect errors and have more accurate reporting.

Optionally, you can also segment the stats by using the campaign parameter. You can use any characters you want, as much as you want. You will have access to read those in your dashboard stats, including the transaction reporting API.

aid && campaign
aid=youraffiliateid&campaign=optional-for-deeper-tracking

2) Location

Latitude and longitude coordinates OR an address must be provided in text format. We recommend using the lat/lng coordinates if you have access to them since they will always be more precise. For the address method, try to feed as much info as possible (venue name, street address, city, and country), as we are using “fuzzy” location matching. Supports all localizations.

lat && lng
lat=40.7505045&lng=-73.9934387

address
address=4 Pennsylvania Plaza, New York, NY 10001

3) Dates

Provide a check-in date OR the event start date. This is needed so the map can poll live availabilities and accurate rates. If omitted, our map will poll availabilities for next year’s date, for 1 night, to show as many properties as possible.

You can send dates in any ISO 8601 format like YYYY-MM-DD. We alternatively also support MM/DD/YYYY. If checkout is empty, it will default to check-in + 1 day.

checkin && checkout
checkin=04/22/2020&checkout=04/24/2020

Alternatively, we can smartly detect the best time to check-in. If you wish to let us do so, provide the data in unix timestamp (seconds) when the event starts. If eventend is not provided, we will select the next day for the check-out from the check-in.

eventstart && eventend
eventstart=1587578400&eventend=1587751200

Note, if you plan to use the eventstart parameter, we’ll automatically assume the unix timestamp’s timezone is GMT. If that isn’t the case, you can send in your timezone offset using the eseetz parameter. For example, if your timestamp’s timezone is in Tokyo’s, send it in like so: eseetz=09:00, or if it’s San Francisco’s: eseetz=-07:00. Do not send in a + since that screws up with the URL structure. You can also send in “auto” so we use the local timezone of the destination location. If omittied, we’ll assume the unix timestamp you are sending is in GMT.

Altogether, the complete URL (that you will wrap through an <iframe>) could look like this:
https://www.stay22.com/embed/gm?aid=affiliateid&lat=40.7505045&lng=-73.9934387&checkin=04/22/2020&checkout=04/24/2020

Widget size

You can change the size of the map using the width and height attributes or CSS properties of the <iframe>

We recommend having the map at a minimum of 450px in height for the ideal display for desktop and tablet sizes.

Tracking campaign and channel performance

You can also segment the stats by using the campaign parameter. You can use any characters you want, as much as you want.

You will have access to read those in your dashboard stats, including the transaction reporting API. To do so, simply add the parameter “campaign” with the variable you want it to keep track of.

The original URL
https://www.stay22.com/embed/gm?aid=affiliateid&lat=40.7505045&lng=-73.9934387&checkin=04/22/2020&checkout=04/24/2020

Would then become
https://www.stay22.com/embed/gm?aid=affiliateid&lat=40.7505045&lng=-73.9934387&checkin=04/22/2020&checkout=04/24/2020&campaign=mobile&campaign=checkout

Below are the most popular parameters. Once you’ve set up the required parameters, you can use the following list to further customize your widget:

Name Type Default Value Description
maincolor hex string 293BFF The main color of the widget in hex (without the #)
markerimage string If set, provide an absolute full URL to change the marker (main map pin) image
venue string If set, this will overwrite the output address and change the map title on the searchbar. Useful to use in combination with lat/lng integrations

Services query parameters

By default, we give the users all choices of services, starting with accommodations. In the future, we’ll smartly detect the best service for the user. Full list is currently: accommodation,experience,carrental,restaurant,parking

Name Type Default Value Description
disableservices string Comma separated list to disable switching into certain services
hidemodeswitcher boolean false True if you want to disable the user completely from changing services
invmode string accommodation The inventory service to show on the default load

Other query parameters

Further customize your widget using the following parameters:

Name Type Default Value Description
adults number 1 Number of adults. Up to a maximum of 30.
children number 0 Number of children. Up to a maximum of 10.
chpincolor hex string If you have custom hotels, in hex (without the #).
chpinfontcolor hex string If you have custom hotels, the font color in hex (without the #).
currency string We automatically detect the user’s currency, but if you wish to force it, we support all currencies. Write in 3 letter format: for e.g: “JPY”.
customfontlink string The full URL for the google font link
customfont string Helvetica Your custom font name.
disableautohover boolean false Automatically set to “true” if you want to disable a recommended listing to automatically hover and pop-up on load.
disabledirections boolean false If set to true, this will hide the polyline generated on hover of a listing.
disablehotels boolean false Disable Stay22’s current hotel provider (HotelsCombined).
disablerentals boolean false Disable Stay22’s current rental provider (Airbnb).
dotlistings boolean false Compact the price pins into dots for more mapping space.
featuredhcids string Comma-separated list of hotel IDs to stand out from other hotels.
fitmaptopoi boolean false If you happen to have Point of Interests (POIs), you can make sure they all show on initial map load.
fontcolor hex string auto The navbar’s font color in hex (without the #).
freezeviewport boolean false If you want to disable automatic zoom out/in when the map is loaded.
hideadults boolean false If set to “true”, the adults field will be hidden.
hidecheckinout boolean false If set to true, the check-in and check-out inputs will be hidden.
hidechildren boolean false If set to true, the children field will be hidden.
hidecurrency boolean false If set to “true”, the currency section will be hidden.
hideenlargemap boolean false If set to “true”, the enlarged map buttons will be hidden.
hidefilters boolean false If set to “true”, the filter button will be hidden.
hideguestpicker boolean false If set to true, the guest picker will be hidden.
hideguestrating boolean false If set to true, the guest rating filter will be hidden.
hideheatmap boolean false If set to true, heatmap selector on the bottom left will be hidden.
hideinfomenu boolean false If set to true, the info/logo button in the top left navbar will be hidden.
hidelanguage boolean false If set to “true”, the language selection will be hidden.
hidemainmarkercover boolean false If set to “true”, the background color behind the main market will be hidden and it will remove the default marker shape.
hidemappanels boolean false If set to true, this will hide map panels (e.g: zoom control, etc.).
hideppn boolean false If set to true, the price information (price per night or total) in the footer will be hidden.
hidepricefilter boolean false If set to true, the budget slider will be hidden.
hidepriceper boolean false If set to “true”, the price per night/total toggle in the dropdown filter menu will be hidden.
hiderooms boolean false If set to true, the rooms field will be hidden.
hideroomtypefilter boolean false If set to “true”, Stay22’s room type filter section from the dropdown filter menu will be hidden.
hidesearchbar boolean false If set to true, the search bar will be hidden.
hidesettings boolean false If set to “true”, the setting button (currency and language) will be hidden.this will hide the setting button (currency and language).
hideshare boolean false If set to “true”, the share button will be hidden.
hidestarrating boolean false If set to true, the star filter will be hidden.
hotelscolor hex string Hotels pin color, in hex (without the #).
hotelsfontcolor hex string Hotels pin font color, in hex (without the #).
isinstantbook boolean false To show only listings that are instantly bookable (for Airbnb).
ljs string We automatically detect the user’s language, but if you wish to force it, we support these languages: (‘en’, ‘fr’, ‘es’, ‘de’, ‘pt’, ‘it’, ‘nl’, ‘pl’, ‘zh’, ‘zh-tw’, ‘ja’, ‘cs’). Please let us know if you have suggestions on which languages we should add next!
loadingbarcolor hex string The loading bar color in hex (without the #).
mapstyle string Choose a theme for the map. Choices are: “default” and “light”. Get in touch with us if you want further options.
max number 1000 Maximum nightly price range in USD. If set to 1000 or more, it’ll assume it’s 1000 or more.
min number 0 Minimum price range per night, in USD.
minguestrating number 1 Minimum guest ratings for Airbnb and Hotel listings. Max of 5.
minstarrating number 1 Minimum stars for hotel listings. Max to 5.
navimage string If set, provide an absolute full URL to change the main logo in the navbar (button on the far left) image.
nelat number To force a map viewport (needs all 4 variables). North-East Latitude.
nelng number To force a map viewport (needs all 4 variables). North-East Longitude.
nopop boolean false If you want to turn off popups of Airbnb and Booking, simply send in true. We have these enabled by default for increased revenue. Forcing an Airbnb and Booking cookie into the user’s browser forged 2.5x more revenue per client. We don’t recommend turning it off, and we made it only pop when there’s an interaction and an intent to travel so it does not disrupt the UX and actually helps your users.
openmenu string If you want to open the menu when the map loads. You can set it as “null” not to open anything. Menu will only open for non-mobile devices if space allows. Options currently are: “null”, “filters”, “info”, “guestpicker”, “datepicker” and “settings”.
priceper string The display price. You can also display it by “total”.
priceslidercolor hex string The price slider color in hex (without the #). If not set, will mimic navbarcolor.
rentalscolor hex string Rentals pin color, in hex (without the #).
rentalsfontcolor hex string Rentals pin font color, in hex (without the #).
rooms number 1 Number of rooms - up to a maximum of 30. Also works as the number of bedrooms for Airbnbs (including studios for the default 1).
scroll string Zooming and dragging is intially disabled by default to avoid conflict with the page. Once we detect user intent, we will automatically enable zoom scrolling. You can force it to be always enabled by setting it as “enabled”.
showairbnbs boolean false Show Airbnbs spaces (filter pre-checked).
showgmapsicon boolean false If set to true, a Google Maps icon on the footer will show for your user’s convenience.
showhotels boolean false Show hotel rooms (filter pre-checked).
showothers boolean false Show alternative spaces like Hostels and Private/Shared rooms (filter pre-checked).
skipabids string Comma-separated list of Airbnb IDs to hide from the map.
skiphcids string Comma-separated list of hotel IDs to hide from the map.
skipotasrp boolean false If you want your users to skip landing on Booking.com’s or Airbnb’s.com search results page and go directly to the hotel details page. Note, we don’t recommend turning this on, as our A/B test shows, it converts better to leave it automatic default to us to control.
supportedcurrencies string To force the list of currencies to your liking. Use commas like “usd,cad,eur” to separate them.
supportedlang string To force the list of language to your liking. Use commas like “en,fr,es,de” to separate them.
swlat number To force a map viewport (needs all 4 variables). South-West Latitude.
swlng number To force a map viewport (needs all 4 variables). South-West Longitude.
zoom number 16 The initial zoom level. The higher the number, the zoomier the map will be

GPX trails on the map

If you want to showcase your trail on the map, we currently support you linking your GPX file to the &gpx= parameter. Make sure the GPX file is hosted in a CORS enabled environment, SSL secured, so we can link to external files and load them.

https://www.stay22.com/embed/gm?lat=45.753075&lng=3.106983&gpx=https://www.example.com/agpxfile.gpx

Example with a GPX trail:

In the future we’ll let you add more than one trail and support for color, weight and among other customization. Just request those features and we’ll cook them up!

Static: Email & social media integration

In order to fetch a snapshot/screenshot of the Stay22 map for your email campaigns, link the image src to our static version of the website by replacing www to static, like so:

https://static.stay22.com/embed/gm?aid=5f43af434354585465998a65&lat=40.742612&lng=-73.987777&venue=Optional%20Text

Example with an <img> tag with 256px/256px:

Please wait for the image to be dynamically generated. Once the snapshot is taken, it will be cached indefinitely. Should you want to refresh the cache, simply send &refresh=true as a query param once.

Extra parameters for static

Name Type Default Value Description
refresh boolean false If you want to flush the cache, then set this as “true”.
resolution number 2 Set resolution for retina screens (2) or set to (1) for normal.
width number 800 Set the width in px.
height number 400 Set the height in px.

FAQ

Will putting an <iframe> in our checkout or confirmation page cause a security risk?
Iframes are completely safe and harmless whereever you decide to embed your Stay22 maps. Iframes are sandboxed and have restricted access due to Same-origin policy. Browsers automatically block iframes and scripts from accessing the parent window object or parent DOM in a third-party context (when the iframe/script domain do not match the parent domain). Read more on MDN

Is the Stay22 map safe in terms of XSS and other vulnerabilities?
We continually test our product from exploits and continually work with bounty hunters to patch holes up. Since we have don’t any user info leaking on Stay22.com domain, any exploit is rather meaningless. That said, we also worked with a security firm and have a clean report if you are interested in reading it. Simply ping us and we’ll dispatch a copy of the report to you.

Will putting an <iframe> ruin our SEO or bleed backlink juice?
Websites around the world feature iframes of Google Maps and Youtube videos to name a few services. Search engine crawlers know how to deal and index properly. Since it’s not direct linking from an <a href=""> and instead it’s from an <iframe>, you will not be giving out backlink juice.

Won’t putting down an <iframe> slow down our page?
Yes and no. No matter what you decide to add to your page, users will end up loading it. The good news is that we worked extra hard to make sure Stay22’s maps don’t load until it’s in the viewport of the user and they can actually see it. This reduces the file size required down to 82 Kb, in other words.. you’re just adding a small “jpeg/picture”, so no noticable difference. You are also free to test us in Google’s PageSpeed insights

What are your cookie policies?
As it stands currently, we only have one cookie originating from Stay22.com. It is a session ID related to an UUID for performance reporting. For e.g: so we get to know when a click, or a booking happens and to which end-user it belongs to. We have 2 other cookies to track users originating from Google Analytics and Mixpanel. Most browsers today refresh (clear and re-assign) those cookies on load of the iframe if the iframe is in third party context.

I noticed a JS console error, should we be worried?
We pride ourselves for not having any console errors coming from our iframe. However, should you notice one, please do report it to us so we fix it asap. We understand during development time it could be a pain to have mixed messages polluting your console.

Tech support

Questions? Email us at hello@stay22.com.
For immediate assistance, use the chat bubble in the bottom right corner to reach us faster!