Deal API

Introductionback to top

You have only but to be approved for a GPN account to gain access to our most up-to-date API and the deluge of 80k+ deals from all our channels (Local, Goods, Getaways and Occasions), will be right at your fingertips. This documentation will walk you through the commonly used terminology, and how to get deals by location, channels, and categories.

Termsback to top

Affiliate Id
This is the unique ID assigned to the Affiliate in GPN to attribute referred sales. To find your Affiliate Id, log into your GPN account and navigate to My Account Account Profile Affiliate Id
Media Id
Specific value assigned to a promotional link in GPN. Please use the following media id: 212556
SID
GPN provides the capability for publishers to pass unique values in their affiliate link to identify where sale actions originate. Loyalty and Rewards publishers may use this parameter to pass a unique member ID in order to credit cash-back or points to its members.
WID
This is an additional Id that can be used to associate a sale with a particular Affiliate website. This Id is useful when an affiliate has multiple websites to differentiate where sales are coming from.
tsToken
This tracking token must be used in all DEAL API calls to identify the affiliate and media that a customer sale originated from.

Example

tsToken=US_AFF_0_201236_212556_0
The following values are assigned to Affiliate Id and Media Id for this example affiliate:
Affiliate Id=201236
Media Id= 212556

Please supply your own Affiliate Id in the tsToken when making your own calls.

UTM tracking parameters
Tracking parameters are used internally to track sales and then attribute those sales to the correct affiliate. They are generated automatically using the tsToken passed to the API. The tracking parameters may be overridden by passing in your values. We highly recommend you contact your affiliate manager before supplying your own parameters as you may not get attributed for the sales you generate.

Example

utm_source=GPN&utm_medium=afl&utm_campaign=201236
where
utm_source=GPN (Traffic Source)
utm_medium=afl (Identifier for a particular traffic source)
utm_campaign=201236 (Your Affiliate Id)

Performance Improvementsback to top

To optimize calls:

  • Use JSON endpoint
  • Include a location value whenever possible (division_id or Lat/lng). If you do not specify a location, the IP address of the invoking device will be used
  • Use pagination to limit the number of deals returned. The maximum number of deals returned is 250 per call

URLback to top

https://partner-api.groupon.com/deals {.json|.xml}

Supported Formatsback to top

  • JSON (default)
  • XML

URL parametersback to top

General

tsToken
  • Required
  • Your identifying tracking server token
  • Example: tsToken=US_AFF_0_201236_212556_0
offset
  • Optional
  • The index (zero-based) of the complete search result set on which to start returning results, up to the provided or default result set size
  • Default: 0
  • Example: offset=0
limit
  • Optional
  • The number of deals to return in the response
  • Default: 30
  • Max limit: 250 per call
  • Example: limit=50

Location

Location can be specified using either division_id or using lat/lng pair with optional radius. If none are provided, the API will use location based off of IP address. If any of these values are present but do not map to a division, the API will return a "Invalid division" 400 response. For example, if you do not use division or lat/lng parameters and your IP address is outside the USA or Canada, then the API may return an error response.

By Division

division_id
  • Optional
  • Used for locating deals in a specific division or city
  • Refer to Division API
  • Example: division_id=chicago

By Lat/lng pair with optional radius

lat
  • Optional
  • Used for locating deals near a specific lat / lng
  • Example: lat=41.896579
lng
  • Optional
  • Used for locating deals near a specific lat / lng
  • Example: lng=-87.643583
radius
  • Optional
  • Specified in miles
  • Default: 10
  • Maximum: 100
  • Example: radius=20

Channels

Channels provide categorized access to deals with a fulfilment or targeting that may differ from Groupon's traditional local deals. Groupon currently supports Local, Goods, Getaways and Occasion channels.

channel_id
  • Optional - If not included, the API will default to local deals
  • The channel to retrieve deals from. Valid values are getaways, goods and occasions
  • Example: channel_id=goods
safe
  • Optional
  • Applies only to goods channel
  • Use to filter out adult deals, defaults to true
  • Example: safe=true

Categories

Returns a list of deals that are currently launched for a specific channel category.

filters=category:
  • Optional
  • Applies only to local and goods channels - use 'categories' URL parameter for getaways channel
  • Append the category you wish to filter on
  • Example: filters=category:food-and-drink
categories
  • Optional
  • Applies only to getaways channel - use 'filters' URL parameter for local and goods channel
  • Example: categories=Pacific
include_travel_bookable_deals
  • Optional
  • Applies only to getaways channel
  • Get getaway deals that have to be booked through our online tool
  • Example: include_travel_bookable_deals=true

Channel Categoriesback to top

The following categories are subject to change. Note that categories are URL encoded.

Local Goods Travel
automotive auto-and-home-improvement cruise-travel
beauty-and-spas baby-kids-and-toys flights-and-transportation
food-and-drink collectibles hotels-and-accommodations
health-and-fitness electronics tour-travel
home-improvement entertainment-and-media  
personal-services for-the-home  
retail groceries-household-and-pets  
things-to-do health-and-beauty  
  jewelry-and-watches  
  mens-clothing-shoes-and-accessories  
  sports-and-outdoors  
  womens-clothing-shoes-and-accessories  

Location Sample Callsback to top

The following sample calls use tsToken=US_AFF_0_201236_212556_0. Please supply your own Affiliate Id in the tsToken when making your own calls.

Get 50 deals for the nearest city (uses IP-based geolocation)

Note that the Deal API will use your IP address and try to map it to division/city. If the Deal API is unable to locate a division/city it will return an error response.

https://partner-api.groupon.com/deals.json?tsToken=US_AFF_0_201236_212556_0&offset=0&limit=50

Channel Sample Callsback to top

The following sample calls use tsToken=US_AFF_0_201236_212556_0. Please supply your own Affiliate Id in the tsToken when making your own calls.

Category Sample Callsback to top

The following sample calls use tsToken=US_AFF_0_201236_212556_0. Please supply your own Affiliate Id in the tsToken when making your own calls.

Get 30 Getaways deals from the areas of Europe, Asia, Africa and Oceania (uses IP-based geolocation)

Note that the Deal API will use your IP address and try to map it to division/city. If the Deal API is unable to locate a division/city it will return an error response.

https://partner-api.groupon.com/deals.json?tsToken=US_AFF_0_201236_212556_0&channel_id=getaways&categories=Europe%2C%20Asia%2C%20Africa%2C%20%26%20Oceania&offset=0&limit=30

Optional tracking informationback to top

The following sample calls use tsToken=US_AFF_0_201236_212556_0. Please supply your own Affiliate Id in the tsToken when making your own calls.

Groupon offers the ability for Affiliates to add parameters to API links to enable the Affiliate to track origination of calls to these links as 2 Affiliate specific parameters; SID and WID. These parameters are NOT required by Groupon, but may be useful to enable an Affiliate to identify specific websites or pages generating clicks and sales, or to pass unique member information in clicks and sales.

If these fields are provided to to the API as call parameters, they are added to the API generated links as-is.

Error Messageback to top

Response Elements

All error responses contain at least the top level error object with httpCode and message

  • httpCode
    HTTP status code
  • message
    Human readable message indicating why the API request failed

Sample Response