Monocle Documentation

You can query any of the following:

  • GET /v2/deals
  • GET /v2/deal/:deal_id
  • GET /v2/product/:product_id

Updated API Keys

Beginning with version 2 of the API, all searches through Monocle must use a valid API key. To obtain a key, please contact us at affiliates@livingsocial.com with your name, company, and a short description of how you intend to use the service.

API Keys must be passed in the X-LivingSocial-API-Key request header, or as the api-key query parameter.

NOTE The v1 API is obsolete, all calls will return 410 GONE.

Location Based Searches

These searches are geo-based, which means they center at a particular coordinate and include all deals physically located within a specified radius. The default radius is 50 miles, and you can change this using the "radius" parameter. Deals will be sorted by distance from the center point by default.

There are two different kinds of deal locations used in this kind of search. The first is the LivingSocial defined city/market. The second is the physical address of the deal's merchant. A deal may have more than one location, and all are included in geo searches. For instance, if a deal's merchant has multiple store locations where a deal may be redeemed, then all store locations as well as the city/market locations are included in the query to find the nearest one to the search center point.

It is important to note that deals that have no actual locate are not included in location searched. This includes national and shop deals, for instance.

It is possible to search only by physical address of the deal's merchant. To do that it is necessary to add a query parameter "use_merchant_location" using "1" as a value.

The following types of searches are considered location based.

  • city
  • coordinate
  • postal code
  • auto located

This endpoint is for searching across our available deals. Each of the following parameters works independently and can be combined to query in different ways, though there is some overlap and some queries may produce no results.

Channel-specific searches

channel string A comma separated list of deal channels to include in the deal results.

http://monocle.livingsocial.com/v2/deals?channel=live_events&api-key=YOUR_API_KEY
http://monocle.livingsocial.com/v2/deals?channel=national&api-key=YOUR_API_KEY
http://monocle.livingsocial.com/v2/deals?channel=shop,travel&api-key=YOUR_API_KEY

Available Channels

In order to understand the return, it's worth understanding the deal channels currently supported by LivingSocial. A deal's "channel" may overlap it's type, but is a separate categorization, and there are search fields available to filter by both.

Location Specific

  • local Location specific deals
  • families Location specific family deals
  • live_events Location specific events and entertainment deals
  • at_home Location specific deals for the home
  • adventures Adventure deals
  • travel Escape deals

Location agnostic (i.e. country-level): these deals are not location specific in that they are available on a national level. Performing location based searches will exclude these deals from the results.

  • national Deals available via national-retailers (i.e. not location dependent)
  • shop Shop product deals

Category-specific searches

category string A comma separated list of categories to include in the deal results. Including multiple categories will include results across all included categories (i.e. all deals in category1 or category2, etc).

http://monocle.livingsocial.com/v2/deals?category=travel&api-key=YOUR_API_KEY
http://monocle.livingsocial.com/v2/deals?category=health,retail&api-key=YOUR_API_KEY

A full list of categories is available in the appendix.

City-specific searches

city integer A city ID.

http://monocle.livingsocial.com/v2/deals?city=1&api-key=YOUR_API_KEY

A full list of city_ids can be found via our location API.

Note that city-specific searches are location-based searches, so the radius parameter does apply.

Country-specific searches

country string An ISO 3166 country code.

http://monocle.livingsocial.com/v2/deals?country=US&api-key=YOUR_API_KEY

Full List of ISO 3166 Country Codes can be found at the www.iso.org website.

Other location-based searches

coords coordinate A lat/lng pair to center the deals search around.

postal_code string US only A US postal code to center the deals search around.

auto_locate boolean default = 0 Set to 1 to center the deals search around your current location. This attempts to geo-locate users by their IP address and may not be completely accurate, particularly on mobile devices. (see also MaxMind city accuracy)

radius integer default = 50 The radius around the given coordinate.

http://monocle.livingsocial.com/v2/deals?coords=38.89,-77.02&api-key=YOUR_API_KEY
http://monocle.livingsocial.com/v2/deals?coords=40.014,-105.270&radius=75&api-key=YOUR_API_KEY
http://monocle.livingsocial.com/v2/deals?auto_locate=1&radius=75&api-key=YOUR_API_KEY

max integer default = 100 The number of deals to include.

page integer default = 1 The result-set to start at. Related to the max parameter.

Searching

search string Performs a search on the text of a deal. This behaves similar to a Google like search. Monocle will returns results that are most relevant to the query terms you entered.

http://monocle.livingsocial.com/v2/deals?search=resorts&api-key=YOUR_API_KEY

Response Formatting

format string default = json Specify the format of the deal results.

The response is a "deals" array and a "cities" array. You may specify a different format using this parameter.

The available formats are:

  • json
  • xml
  • jsonp

full boolean default = 0 Set to 1 to force the full deal representation.

callback string default = LSJsonpCallback jsonp only Name the callback function to be used when specifying the response format as "jsonp".

Result Sorting

sort string Specify the sort field of the deal results.

By default (if not parameters are passed in), deals are sorted in reverse-chronological order by their end dates; deals expiring soonest will appear first. When doing a location based search, deals are sorted by their distance to the search location (i.e. city, zip code, coordinate, etc). This parameter will sort the result as specified. If you perform a search query the results will be sorted by relevance to your search parameter.

The available sort options are:

  • facebook_shares
  • twitter_shares
  • orders_count

desc boolean default = 0 Set to 1 to reverse sort the search results; results are sorted by the specified field in ascending order by default. For use with the sort param.

Expired Deals

include_expired boolean default = 0 Set to 1 to include deals that are expired. NOTE: These deals cannot be purchased.

Non Commissionable Deals

non_commissionable boolean default = 0 Set to 1 to include deals that are non commissionable.

Update Beginning in March 2014, the default behavior of the deals search api will be to return deals regardless of comissionable state. Partners may update their use of the api to filter non commissionable deals if they desire by the non_commissionable attribute which is available on the full deal representation objects.

GET /v2/deal/:deal_id

deal_id integer required The deal id.

http://monocle.livingsocial.com/v2/deal/1?api-key=YOUR_API_KEY

product_id integer required The product id.

http://monocle.livingsocial.com/v2/product/1?api-key=YOUR_API_KEY

Response

The response for the deals search is as an object with two lists, one containing the matching deals, the other containing the corresponding cities (i.e. markets).

Deal Fields

id number The specific deal ID

deal_type string The LivingSocial deal type

channel string The marketing/partner channel of the deal

url string Deal URL

short_title string long_title string Short and long titles of the deal

description string full only The full text description of the deal; this field may contain HTML.

fine_print string full only A text list of details about the deal

locations array[object] full only A list of location objects

merchant_name string The full name of the deal's merchant

image object An image object containing a deals "primary" image in several widths: 700, 360 and 220. (NOTE: base image dimensions vary by deal type.)

images array[object] A list of image objects for the deal. (NOTE: base image dimensions vary by deal type.)

offer_starts_at string offer_ends_at string An ISO 8601 encoded date that represents the begin/end dates of the deal, in UTC

orders_count number Total purchases currently recorded

facebook_shares number twitter_shares number Social share counts

categories array[string] All categories associated with the deal; can be one or many

city_ids array[number] A list of the city ID's the deal is tethered to; can be one or many. The corresponding city objects are included in the response as a sibling to the root "deals" array.

options array[object] A deal can have multiple options for purchase. See option

nation_wide boolean True if the deal is considered "nation-wide" (i.e. available throughout the nation it is located within).

distance  number optional If this is a location based search, the distance is the number of miles from the center point.

City Fields

id number The city ID

name string The full name of the city/market

latlng array/coordinate A geo coordinate formated as a latitude+longitude pair.

Option Fields

description string A description of the option for display.

price number The price of the option that LivingSocial is offering.

discount number The discount amount of the (original_price - price).

original_price number The oringal price from the vendor.

savings number The percent savings when comparing the origina_price to the LivingSocial price.