Deals API

Publisher Documentation

A RESTful web-based API.

All API requests require authentication in order to identify you, which is achieved by way of a unique consumer_key. If you do not have a key, please contact us and we will create a publisher account and generate your key.

When making API requests, simply pass your consumer_key as a URL parameter for GET requests or within the POST body, or as the value of the Authorization header.

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

All results returned in list methods are paginated. The default is 20 items per page, with an upper limit of 30. But you can set the per_page parameter to override this. You can also tell the API which page to return using the page parameter, which obviously has a default of 1 (being the first page).

The pagination info is included in the Link header (Linebreak is included for readability):

  Link: <https://api.deals.shermanstravel.com/v1/deals?page=3&per_page=10>; rel="next",
    <https://api.deals.shermanstravel.com/v1/deals?page=6&per_page=10>; rel="last"
      

The possible rel values are:

next
Shows the URL of the immediate next page of results.
last
Shows the URL of the last page of results.
first
Shows the URL of the first page of results.
prev
Shows the URL of the immediate previous page of results.

You can send a ?callback parameter to any GET call to have the results wrapped in a JSON function. This is typically used when browsers want to embed Deals content in web pages by getting around cross domain issues. The response includes the same data output as the regular API, plus the relevant HTTP Header information.

        $ curl http://api.deals.shermanstravel.com?callback=foo

        foo({
          "deals": [
            {
              "id":195,
              "title":"$86+: Brooklyn Downtown Hotel w/3rd Night Free"
            }
          ]
        })
      
GET

Fetches a single deal including all associated data.

Parameter Value Type Default Description
consumer_key integer Your unique API key used for authentication
id integer The ID (primary key) of the deal record you wish to fetch
format string json Output format as json or xml
Ajax loader Complete the fields above and click the button on the left to try this method


Request

  
Response headers

  
Response body

GET

Fetches a single deal including all associated data.

Parameter Value Type Default Description
consumer_key integer Your unique API key used for authentication
format string json Output format as json or xml
ids string

Pass multiple ids separated by comma.

categories string

Limit results to those that belong to the given category. Possible values are flight, hotel, vacation, cruise and car-rental.

Split multiple categories with a comma flight,car-rental

exclude_categories string

Limit results to those that do NOT belong to the given category or categories. Possible values are flight, hotel, vacation, cruise and car-rental.

Split multiple categories with a comma flight,car-rental

partners integer

Limit results to those that belong to the given partner ID(s).

Split multiple partner ID's with a comma 1,2

exclude_partners integer

Limit results to those that do NOT belong to the given partner ID(s).

Split multiple partner ID's with a comma 1,2

tags string

Limit results to those that are tagged with the passed tag(s).

Split multiple tag names with a comma tag1,tag2. Tags can have spaces, but should not include spaces between tags. So this is fine tag one,tag2, but this is not tag one, tag2.

By default, if you pass more than one tag, those deals tagged with either of the given tags will be returned. use the all() qualifier to match deals that are tagged with all the given tags.

Example: all(tag one,tag two)

exclude_tags string

Limit results to those that are NOT tagged with the passed tag(s).

Split multiple tag names with a comma tag1,tag2. Tags can have spaces, but should not include spaces between tags. So this is fine tag one,tag2, but this is not tag one, tag2.

By default, if you pass more than one tag, those deals tagged with either of the given tags will not be returned.

geotags string

Limit results to those that are geo-tagged with the passed place(s).

Split multiple places with a comma london,new york.

By default, if you pass more than one place, those deals geo-tagged with either of the given places will be returned. use the all() qualifier to match deals that are geo-tagged with all the given places.

Example: all(london,new york)

You can also pass in a selection of "modifiers", which will help you be more specific with the places you want to match. Allowed modifiers are country, state and geotag type (A geotag always has a type, which is one of origin, destination or stopover. If a type is not given, then deals geotagged with any type will be returned.).

Examples: paris[country=FR] or washington[state=DC] or london[type=origin]

You can also query by state, country and even region:

Examples: ny[state] or us[country]

You can mix and match any of the above qualifiers and modifiers.

Example: all(london[country=UK],washington[country=US][state=DC]).

cascade_down boolean true

When true it expands the geotags filter to include the children of the given places.

Example: when using "geotags=london[city][country=GB]" with cascade_down set to true, the deals returned will be all the deals geotagged with london or with any place than is a child of london, like the london airports. Setting cascade_down to false will only return the deals that are geotagged with london.

Note:When the geotags field has an all qualifier, the cascade_down is always false if it's forced to true.

cruise_lines integer

Limit results to those that belong to the given cruise line ID(s).

Only applies to cruise deals

Split multiple cruise line ID's with a comma 1,2

exclude_cruise_lines integer

Limit results to those that DO NOT belong to the given cruise line ID(s).

Only applies to cruise deals

Split multiple cruise line ID's with a comma 1,2

ships integer

Limit results to those that belong to the given ship ID(s).

Only applies to cruise deals

Split multiple ship ID's with a comma 1,2

exclude_ships integer

Limit results to those that DO NOT belong to the given ship ID(s).

Only applies to cruise deals

Split multiple ship ID's with a comma 1,2

minimum_price float

Limit results to deals whose price range starts at least at the given value.

maximum_price float

Limit results to deals whose price range does not exceed the given value.

minimum_ppn float

Limit results to deals whose price per night range starts at least at the given value.

maximum_ppn float

Limit results to deals whose price per night range does not exceed the given value.

randomise boolean 0 If true, records will be randomised.
include_taggings boolean false

Tags and geotags are not returned by default, but if this parameter is set to true, each returned deal will include its tags and geotags.

Please note that including taggings can slow down the response, especially if the response returns a lot of deals.

device string all

Limit results to deals that are device specific. Possible values are all, desktop and mobile.

page integer 1 The page number to return
per_page integer 20 The maximum records to return per page (max is 20)
Ajax loader Complete the fields above and click the button on the left to try this method


Request

  
Response headers

  
Response body

GET

Optimal option for Infinite Scrolling and a better alternative to deep pagination.

How it works
In the 2nd request, only the consumer_key and scroll_id are required. We will maintain a session open for 5 minutes, so the filters applied in the 1st request will automatically be applied in all subsequent requests as long as you send the scroll_id (received in the 1st request).

Parameter Value Type Default Description
consumer_key integer Your unique API key used for authentication
scroll_id string Exclude in 1st request
format string json Output format as json or xml
categories string

Limit results to those that belong to the given category. Possible values are flight, hotel, vacation, cruise and car-rental.

Split multiple categories with a comma flight,car-rental

exclude_categories string

Limit results to those that do NOT belong to the given category or categories. Possible values are flight, hotel, vacation, cruise and car-rental.

Split multiple categories with a comma flight,car-rental

partners integer

Limit results to those that belong to the given partner ID(s).

Split multiple partner ID's with a comma 1,2

exclude_partners integer

Limit results to those that do NOT belong to the given partner ID(s).

Split multiple partner ID's with a comma 1,2

tags string

Limit results to those that are tagged with the passed tag(s).

Split multiple tag names with a comma tag1,tag2. Tags can have spaces, but should not include spaces between tags. So this is fine tag one,tag2, but this is not tag one, tag2.

By default, if you pass more than one tag, those deals tagged with either of the given tags will be returned. use the all() qualifier to match deals that are tagged with all the given tags.

Example: all(tag one,tag two)

exclude_tags string

Limit results to those that are NOT tagged with the passed tag(s).

Split multiple tag names with a comma tag1,tag2. Tags can have spaces, but should not include spaces between tags. So this is fine tag one,tag2, but this is not tag one, tag2.

By default, if you pass more than one tag, those deals tagged with either of the given tags will not be returned.

geotags string

Limit results to those that are geo-tagged with the passed place(s).

Split multiple places with a comma london,new york.

By default, if you pass more than one place, those deals geo-tagged with either of the given places will be returned. use the all() qualifier to match deals that are geo-tagged with all the given places.

Example: all(london,new york)

You can also pass in a selection of "modifiers", which will help you be more specific with the places you want to match. Allowed modifiers are country, state and geotag type (A geotag always has a type, which is one of origin, destination or stopover. If a type is not given, then deals geotagged with any type will be returned.).

Examples: paris[country=FR] or washington[state=DC] or london[type=origin]

You can also query by state, country and even region:

Examples: ny[state] or us[country]

You can mix and match any of the above qualifiers and modifiers.

Example: all(london[country=UK],washington[country=US][state=DC]).

cascade_down boolean true

When true it expands the geotags filter to include the children of the given places.

Example: when using "geotags=london[city][country=GB]" with cascade_down set to true, the deals returned will be all the deals geotagged with london or with any place than is a child of london, like the london airports. Setting cascade_down to false will only return the deals that are geotagged with london.

Note:When the geotags field has an all qualifier, the cascade_down is always false if it's forced to true.

cruise_lines integer

Limit results to those that belong to the given cruise line ID(s).

Only applies to cruise deals

Split multiple cruise line ID's with a comma 1,2

exclude_cruise_lines integer

Limit results to those that DO NOT belong to the given cruise line ID(s).

Only applies to cruise deals

Split multiple cruise line ID's with a comma 1,2

ships integer

Limit results to those that belong to the given ship ID(s).

Only applies to cruise deals

Split multiple ship ID's with a comma 1,2

exclude_ships integer

Limit results to those that DO NOT belong to the given ship ID(s).

Only applies to cruise deals

Split multiple ship ID's with a comma 1,2

minimum_price float

Limit results to deals whose price range starts at least at the given value.

maximum_price float

Limit results to deals whose price range does not exceed the given value.

minimum_ppn float

Limit results to deals whose price per night range starts at least at the given value.

maximum_ppn float

Limit results to deals whose price per night range does not exceed the given value.

include_taggings boolean false

Tags and geotags are not returned by default, but if this parameter is set to true, each returned deal will include its tags and geotags.

Please note that including taggings can slow down the response, especially if the response returns a lot of deals.

device string all

Limit results to deals that are device specific. Possible values are all, desktop and mobile.

per_page integer 20 The default number of records per page is 20 (max is 30)
Ajax loader Complete the fields above and click the button on the left to try this method


Request

  
Response headers

  
Response body

Advertiser Conversion Pixel

Cookie-based Conversion Pixel

Place the below pixel on your booking or email signup confirmation page, making sure to replace the "TYPE" value with the "booking" or "signup" value accordingly. You must also replace the "PARTNER_ID" value with an unique ID provided by ShermansTravel. You may also optionally pass a "label" value. Please ensure it is persisted to your confirmation page, so it may be inserted into the pixel on this page. For assistance with implementation, please contact: development@shermanstravelmedia.com

      <!-- Please Use This Test Pixel For Testing Only -->
      <img src="https://staging.click.deals.shermanstravel.com/{PARTNER_ID}/convert.gif?type={TYPE}&label={LABEL}" rel="nofollow" alt="" height="1" width="1">
      <img src="https://staging.clicks.shermanscruise.com/{PARTNER_ID}/convert.gif?type={TYPE}&label={LABEL}" rel="nofollow" alt="" height="1" width="1">
    
      <!-- Please Use This Pixel In Production -->
      <img src="https://click.deals.shermanstravel.com/{PARTNER_ID}/convert.gif?type={TYPE}&label={LABEL}" rel="nofollow" alt="" height="1" width="1">
      <img src="https://clicks.shermanscruise.com/{PARTNER_ID}/convert.gif?type={TYPE}&label={LABEL}" rel="nofollow" alt="" height="1" width="1">
    
Examples:
      <!-- Booking conversion pixel without label -->
      <img src="https://click.deals.shermanstravel.com/{PARTNER_ID}/convert.gif?type=booking" rel="nofollow" alt="" height="1" width="1">
      <img src="https://clicks.shermanscruise.com/{PARTNER_ID}/convert.gif?type=booking" rel="nofollow" alt="" height="1" width="1">
    
      <!-- Email signup conversion pixel with label -->
      <img src="https://click.deals.shermanstravel.com/{PARTNER_ID}/convert.gif?type=signup&label=a-sample-label" rel="nofollow" alt="" height="1" width="1">
      <img src="https://clicks.shermanscruise.com/{PARTNER_ID}/convert.gif?type=signup&label=a-sample-label" rel="nofollow" alt="" height="1" width="1">
    


URL-based Conversion Pixel

Place the below pixel on your booking confirmation page, making sure to replace the "stsid" value with the "stsid" value found in the URL. ShermansTravel will pass this "stsid" value to your landing page: please ensure it is persisted to your confirmation page, so it may be inserted into the pixel on this page. For assistance with implementation, please contact: development@shermanstravelmedia.com

      <!-- Please Use This Test Pixel For Testing Only -->
      <img src="https://staging.click.deals.shermanstravel.com/convert.gif?stsid={STSID}" rel="nofollow" alt="" height="1" width="1">
    
      <!-- Please Use This Pixel In Production -->
      <img src="https://click.deals.shermanstravel.com/convert.gif?stsid={STSID}" rel="nofollow" alt="" height="1" width="1">
    

Small Widget

Deals can also be consumed and exposed via a simple but powerful Javascript based widget, which allows you to drop a few lines of code directly onto your site's HTML pages. This will then render a nicely formatted widget containing a few deals.

At present, there is only one widget design, but it accepts almost the same options as the REST API. The following options are supported and abide by the same formatting rules as the REST API category, exclude_category, no_follow, partner, exclude_partner, tag, exclude_tag, geotag and exclude_geotag (see the #list method for more info on each of these options).

<script src="http://autocomplete.shermanstravel.com/assets/widget.js"></script>
<script type="text/javascript">
  new DealsWidget('your api key');
</script>
<script src="http://autocomplete.shermanstravel.com/assets/widget.js"></script>
<script type="text/javascript">
  new DealsWidget('your api key' { no_follow: true });
</script>
<script src="http://autocomplete.shermanstravel.com/assets/widget.js"></script>
<script type="text/javascript">
  new DealsWidget('your api key', { categories: 'hotel' });
</script>
<script src="http://autocomplete.shermanstravel.com/assets/widget.js"></script>
<script type="text/javascript">
  new DealsWidget('your api key', { tag: 'romance' });
</script>
<script src="http://autocomplete.shermanstravel.com/assets/widget.js"></script>
<script type="text/javascript">
  new DealsWidget('your api key', { use_images: true });
</script>

SHT Widgets



<script src="http://autocomplete.shermanstravel.com/v1/widget/widget.js"></script>
<div id="sht_custom_widget_example"></div>
<script type="text/javascript">
  new SHTWidget('apikey13', 'Most Popular Deals', {container_id: "sht_custom_widget_example" });
</script>

SHT Full Page Widget

<div id="full_page_example_1"> #widget container 1 </div>

<script src="http://autocomplete.shermanstravel.com/v1/widget/fp_script.js"></script>
<script type="text/javascript">
  new SHTFullPageWidget({
    consumer_key: 'your api key',
    container_id : 'full_page_example_1'
  });
</script>
#widget container 1

SHT Large Widget

<div id="example_1"> #widget container 1 </div>
... ( Widget will inherit the size of its parent )
<script src="http://autocomplete.shermanstravel.com/v1/widget/script.js"></script>
<script type="text/javascript">
  new SHTLargeWidget({
    consumer_key: 'your api key',
    container_id : 'example_1'
  });
</script>
#widget container 1
<div id="example_2"> #widget container 2 </div>

... ( Widget will force the size to a wider space )

<script src="http://autocomplete.shermanstravel.com/v1/widget/script.js"></script>
<script type="text/javascript">
  new SHTLargeWidget({
    consumer_key: 'your api key',
    container_id : 'example_2',
    expansive: true
  });
</script>
#widget container 2
<div id="example_3"> #widget container 3 </div>

... ( Widget will force the size to a wider space )

<script src="http://autocomplete.shermanstravel.com/v1/widget/script.js"></script>
<script type="text/javascript">
  new SHTLargeWidget({
    consumer_key: 'your api key',
    container_id : 'example_3',
    no_follow: true
  });
</script>
#widget container 3

SHT Widget Orange

<div id="example_5"> #widget orange 1 </div>
... ( Widget will inherit the size of its parent )
<script src="http://autocomplete.shermanstravel.com/v1/widget/script.js"></script>
<script type="text/javascript">
  new SHTLargeWidget({
    consumer_key: 'your api key',
    container_id : 'example_5',
    theme: 'orange'
  });
</script>
#widget orange 1
<div id="example_6"> #widget orange 2 </div>
... ( Widget will inherit the size of its parent )
<script src="http://autocomplete.shermanstravel.com/v1/widget/script.js"></script>
<script type="text/javascript">
  new SHTLargeWidget({
    consumer_key: 'your api key',
    container_id : 'example_6',
    theme: 'orange',
    condensed: true
  });
</script>
#widget orange 1