MAP Developer documentation

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.

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

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=affiliateid&lat=40.742612&lng=-73.987777" id="stay22-widget" width="100%" height="460" frameborder="0"></iframe>

The code above will generate this map:

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

Having a partner 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

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, country, etc.), as we are using “fuzzy” location matching. Supports all localizations.

lat && lng
lat=40.7505045&lng=-73.9934387
Make sure if your lat/lng is inside China, to send us the type of coordinate system you are using. By default Stay22 parses WGS. However, if your latlngs are from Google Map (GCJ) or Baidu (BD), please specify using the &coordtype=WGS|GCJ|BD. 

Read more here.

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

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=2022-04-22&checkout=2022-04-24

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 event end 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 omitted, we’ll assume the unix timestamp you are sending is in GMT.

By default, your iframe will be the Stay22 Hybrid Map. Map (only) or ListView will only be displayed in the iframe if you implement the below parameters.

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:

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. Currently the full list is: accommodation,experience,restaurant

To further customize your widget, using the following parameters:

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

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

Example with a GPX trail:

If you want to show your own pins on the map, you will have to use waypoints <wpt/> or routes <rte/>. For example:

<rte>
  <rtept lat="42.00525899999999" lon="-87.88783000000001">
    <time>2021-10-01T19:00:00-05:00</time>
    <name>Allstate Arena</name>
    <desc>Rosemont, IL</desc>
    <link href="https://example.com/e/102196052" />
    <extensions>
      <icon href="https://photos.example.com/thumb/11632120.jpeg" />
    </extensions>
  </rtept>
  [...]
</rte>

<!-- REQUIRED: The pin coordinates -->
<wpt lat="32.753186" lon="-117.208596">
  <!-- OPTIONAL: The pin hover's info card -->
  <name>Mount Sinai</name>

  <!-- OPTIONAL: The pin link if clicked -->
  <link href="https://example.com/e/102694808" />

  <!-- OPTIONAL: The pin's image -->
  <extensions>
    <icon href="https://photos.example.com/thumb/9944463.jpeg" />
  </extensions>
</wpt>
[...]

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=affiliateid&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: