You can query any of the following:
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 email@example.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.
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.
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 string A comma separated list of deal channels to include in the deal results.
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 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.
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).
A full list of categories is available in the appendix.
city integer A city ID.
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 string An ISO 3166 country code.
Full List of ISO 3166 Country Codes can be found at the www.iso.org website.
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.
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.
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.
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:
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".
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:
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.
include_expired boolean default = 0 Set to 1 to include deals that are expired. NOTE: These deals cannot be purchased.
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.
deal_id integer required The deal id.
product_id integer required The product id.
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).
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.
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.
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.