Groupon API Documentation

Search this site

Deals API

Retrieving Featured Deal


URL:
    http://www.groupon.com/api/v1/deals

Supported Formats:
    JSON / XML


Description:
    Returns a list of deals.  The API returns an ordered list of deals currently running for a given Division.  Priority is based on position within the response (top deals are higher in priority).


Query Parameters:
    lat - Latitudinal coordinates of the caller
    lng - Longtitudinal coordinates of the caller


Deal Response


id
    Description: A unique identifier for a specific deal.  Allowable characters include [a-z][0-9][-], and will contain no whitespace.
    Example: my-great-restaurant-deal

deal_url
    Description: A URL for the deal as it can be accessed on the main Groupon site.  This would be the same URL a user would enter to access the deal in a web browser.
    Example: http:///www.groupon.com/deals/green-door-tavern

title
    Description: A one-line summary of the deal.
    Example: $10 for $25 Worth of Food and Drink at Green Door Tavern

small_image_url
medium_image_url
large_image_url
    Description: Fixed size URLs for the main image associated with the deal
    Example: http://www.groupon.com/images/site_images/0010/8552

division_id
    Description: A unique identifier for the division that the deal is located in.  Allowable characters include [a-z][0-9][-], and will contain no whitespace.  The identifier for a division may or may not be geographic in nature.
    Example: minneapolis-stpaul

division_name
    Description: The human-readable form of the division id.
    Example: Minneapolis / St Paul

division_lat
division_lng
    Description: Geographic coordinates.  These coordinates will only appear in cases where the division is geographic in nature.  Groupon reserves the right to define divisions which span multiple geographic regions, and in this case, geographic coordinate smay not present.
    Example: 41.88941 , -87.624039

division_timezone
    Description: The timezone for the division.  This field will only be populated in cases where the division represents a distinct geographic location.  If the division represents a logical area that spans multiple timezones, this field will be absent.
    Example: America/Chicago

division_offset_gmt
    Description: An offset, in seconds, from GMT.  This field will only be present in cases where the division is located in a specific timezone.
    Example: -18000

vendor_id
    Description: A unique identifier for the vendor providing this deal.  Allowable characters include [a-z][0-9][-], and will contain no whitespace.
    Example: green-door-tavern

vendor_name
    Description: A human-readable form of the vendor id.
    Example: Green Door Tavern

vendor_website_url
    Description: The external URL for the vendor, if available.  This URL will not point back to any content on groupon.com.
    Example: http://www.greendoorchicago.com

status
    Description: The status of the deal.  A deal will either be 'open', or 'closed' depending on whether it is currently active and allowing purchases, or no longer available for purchase.
    Example: open

start_date
    Description: The date and time at which the deal became available (status: open), represented in UTC.
    Example: 2009-09-10T05:00:00.000-00:00

end_date
    Description: For closed deals, the date and time at which the deal no longer became available.  For deals that are currently open, this represents the closing date and time of the deal.
    Example: 2009-09-11T04:59:59.999-00:00

tipped
    Description: A boolean value (true, false) that indicates whether this deal has tipped.  A deal is considered 'tipped' when it reaches a tipping point, whereby a minimum number of members join.
    Example: true / false

tipping_point
    Description: The minimum number (zero or more) of purchases that must be met by all participants in the deal in order for the deal to tip.
    Example: 100

tipped_date
    Description: For any deals that have tipped, the date and time at which the deal tipped.  For deals that did not tip, this field will not be present.
    Example: 2008-12-22T11:44:23.201-00:00

sold_out
    Description: A boolean value indicating whether the deal had specified a limited quantity available, and that quantity sold out.  This provides an easy way for clients to visually indicate that the deal ended early due to a limited quantity being depleted.  If the deal does not have limits applied, or has not yet sold out, this value will be false.
    Example: true / false

quantity_sold
    Description: The number of units sold so far.  For deals that have closed, this number represents the total number of units sold.
    Example: 174

price
    Description: The discounted cost of each unit to the customer.
    Example: 40.00USD

value
    Description: The actual value of the Groupon.  This is effectively the full value of the Groupon when it is redeemed.
    Example: 80.00USD

discount_amount
    Description: 
    Example: 

discount_percent
    Description: The discounted percent (0-100).  This is effectively the same as (price / value * 100).
    Example: 60

shipping_address_required
    Description: Groupons which would require a user to enter a shipping address.  This denotes a deal whose purchase will require the user to supply such an address in order to redeem.
    Example: true / false

limited_quantity
    Description: This flag dictates whether or not there are only a limited quantity of inventory available for this deal.  Once this limit is reached, the deal is 'sold out' (see above).
    Example: true / false

initial_quantity
    Description: The initial quantity available.  If quantity is limited, this value will normally not change, unless the merchant / vendor decides to open up more inventory once the deal is launched.
    Example: 250

quantity_remaining
    Description: The quantity still available for purchase.  Upon launching, this value will equal the 'initial quantity'.  For deals that sell out, this will equal zero.
    Example: 249

minimum_purchase
    Description: The minimum amount that a customer must order in order to purchase this deal.
    Example: 2

maximum_purchase
    Description: The maximum number which any single customer is allowed to purchase.  In rare cases this number may be '1', but normally 
    Example: 7

expiration_date
    Description: The date at which a voucher will expire.
    Example: 2011-03-23T04:59:00Z

details
    Description: An array of details and restrictions for this deal.  This is effectively the 'Fine Print' which appears on the site itself.
    Example: Limit 1 per person. May purchase 1 additional as gift.




Sample Response (JSON)
{
  "status": {
    "code": 0,
    "message": "OK"
  },
  
  "deals":
  [
    {
      "id": "spring-restaurant-deal",
      "deal_url": "http://www.groupon.com/deals/green-door-tavern/",
      "title": "$10 for $25 Worth of Food and Drink at Green Door Tavern",
      "small_image_url": "http://www.groupon.com/images/site_images/0010/8551",
      "medium_image_url": "http://www.groupon.com/images/site_images/0010/8552",
      "large_image_url": "http://www.groupon.com/images/site_images/0010/8553",
      "division_id": "chicago",
      "division_name": "Chicago",
      "division_lat": 41.88941,
      "division_lng": -87.624039,
      "division_timezone": "America/Chicago",
      "division_offset_gmt": -18000,
      "vendor_id":  "green-door-tavern",
      "vendor_name": "Green Door Tavern",
      "vendor_website_url": "http://greendoorchicago.com/",
      "status": "open",
      "start_date": "2009-09-10T05:00:00.000-00:00",
      "end_date": "2009-09-11T04:59:59.999-00:00",
      "tipped": false,
      "tipping_point": 100,
      "tipped_date": "2009-09-11T04:59:59.999-00:00",
      "sold_out": false,
      "quantity_sold": 83,
      "price": "30.00USD",
      "value": "60.00USD",
      "discount_amount": "30.00USD",
      "discount_percent": 50,
      "conditions": {
        "limited_quantity": true,
        "initial_quantity":1000,
        "quantity_remaining": 43,
        "minimum_purchase": 2,
        "maximum_purchase": 4,
        "expiration_date": "2010-04-21T23:59:59.000-05:00",
        "details": [
          "New customers only",
          "Limit 1 per person",
          "May purchase multiple as gifts",
          "Reservations recommended"
        ]
      }
    }
  ]
}

Sample Response (XML)
<?xml version="1.0"?>
<response code="0" message="OK">
  <deals>
    <deal>
      <id>spring-restaurant-deal</id>
      <deal_url>http://www.groupon.com/deals/green-door-tavern/</deal_url>
      <title>$10 for $25 Worth of Food and Drink at Green Door Tavern</title>
      <small_image_url>http://www.groupon.com/images/site_images/0010/8551</small_image_url>
      <medium_image_url>http://www.groupon.com/images/site_images/0010/8552</medium_image_url>
      <large_image_url>http://www.groupon.com/images/site_images/0010/8553</large_image_url>
      <division_id>chicago</division_id>
      <division_name>Chicago</division_name>
      <division_lat>41.88941</division_lat>
      <division_lng>-87.624039</division_lng>
      <division_timezone>America/Chicago</division_timezone>
      <division_offset_gmt>-18000</division_offset_gmt>
      <vendor_id>green-door-tavern</vendor_id>
      <vendor_name>Green Door Tavern</vendor_name>
      <vendor_website_url>http://greendoorchicago.com/</vendor_website_url>
      <status>open</status>
      <start_date>2009-09-10T05:00:00.000-00:00</start_date>
      <end_date>2009-09-11T04:59:59.999-00:00</end_date>
      <tipped>false</tipped>
      <tipping_point>100</tipping_point>
      <tipped_date>2009-09-11T04:59:59.999-00:00</tipped_date>
      <sold_out>false</sold_out>
      <quantity_sold>83</quantity_sold>
      <price>30.00USD</price>
      <value>60.00USD</value>
      <discount_amount>30.00USD</discount_amount>
      <discount_percent>50</discount_percent>
      <conditions>
        <limited_quantity>true</limited_quantity>
        <initial_quantity>1000</initial_quantity>
        <quantity_remaining>43</quantity_remaining>
        <minimum_purchase>2</minimum_purchase>
        <maximum_purchase>4</maximum_purchase>
        <expiration_date>2010-04-21T23:59:59.000-05:00</expiration_date>
        <details>
          <detail>New customers only</detail>
          <detail>Limit 1 per person</detail>
          <detail>May purchase multiple as gifts</detail>
          <detail>Reservations recommended</detail>
        </details>
      </conditions>
    </deal>
  </deals>
</response>


Retrieving Featured Deal by Division

URL:
    http://www.groupon.com/api/v1/:division_id/deals

Supported Formats:
    JSON / XML


Description:
    Returns a list of deals for a specified division (currently will return only a single, featured deal).  The division must be a valid division as returned through the divisions API.


Sample Request:
    http://www.groupon.com/api/v1/chicago/deals
    http://www.groupon.com/api/v1/new-york/deals