Groupon API
Version: 1.0
About the Groupon API
The goal of this API is to allow applications to directly interact with Groupon via a REST API. This document describes supported aspects of the API, focusing primarily on exposure of deal content based on geography.
API Token
An API token will be required on all inbound requests. This token is a 40 character string is generated by the system as part of signing up to use the API. and should be sent as an HTTP header using the key 'X-GrouponToken', and is verified by the system on each request. This token is tied to the API developer, and will be used to enforce rate limits on API access (see below).
Rate Limits
By supplying an API token, the system places a cap on the maximum number of requests allowed per minute by instance based on a combination of inbound IP address and API token. Deal content changes throughout the day on the site and may require applications to refresh their views of the data accordingly, but we expect API developers to avoid excessive polling of data. Rate limits exist primarily to prevent abuse, as well as to allow us to monitor usage patterns across all API clients. Typical apps should likely avoid refreshing data for the same end-user more than once a minute, for example. The system will return an HTTP status code of 503 in cases where the call is refused due to rate limiting.
Supported Formats
JSON and XML formats will be supported. Naming conventions for elements throughout the API will use underscores (i.e. "this_is_valid") rather than camel-case. Specifying a supported format type on any request will return a response in that format. The format may be specified by appending an extension at the end of a URL (.xml, or .json), or passing a 'format' parameter as part of the query string (i.e. 'format=json').
Error Handling
HTTP error codes will be returned in response headers, unless the caller chooses bypasses this functionality and assumes responsibility for parsing the content of the response while receiving an HTTP status code of 200 (OK) (this is only suggested for developers using frameworks that do not support parsing of HTTP response headers).
Each response will contain a result code, and an optional message associated with it, such as follows:
| Type | Description | Example
|
| JSON | Status element will appear at the top level of response | 'status': {
'code' : 0
'message': "OK"
} |
| XML | A top-level response element contains attributes detailing the code & message | <response code="0" message="OK">
...
</response> |
API Versioning
The requested version number of the API must be supplied on each request. Examples are as follows:
http://www.groupon.com/api/v1/boston/deals
http://www.groupon.com/api/v1/divisions
Currently there is only one supported version of the API. Features may be added throughout the life of a specific version of the API, but structural or semantic changes will only appear in subsequent versions.
Version numbers will increment in whole numbers (i.e. 'v2', 'v3', etc). As a new version becomes available, the prior version of the API will be sunsetted, and new features should only be expected to appear in the newer version. At that time, the prior version of the API will continue to be supported for some period of time which will be determined and communicated at that time.
Dates & Times
Throughout the API, date and time fields will be specified in ISO 8601 format. All times should be assumed to be returned in UTC. In order to avoid ambiguities, however, timezone will always be present in any date & time field as an offset. See http://en.wikipedia.org/wiki/ISO_8601 for more information.
Because time will always be expressed as UTC, it is the responsibility of the API developer to parse and adjust these values accordingly. The API will document places in which these values refer to a specific geographic timezone.
Examples:
2009-11-30 (date only)
2009-11-30T22:04:59-00:00 (date & time)
Currency
Currency is represented as string values composed of a decimal value followed by a three letter currency code. See http://en.wikipedia.org/wiki/ISO_4217 for more information. The decimal value will not have any locale-specific formatting applied to it. A period ('.') will signify the decimal in any and all supported currency types.
Examples:
0.00USD (zero amount)
5400.50GBP (large amounts >= 1000 do not have any other formatting applied)
Images
Displaying image content is crucial for communicating both details and attractiveness of a deal. Since API developers may be working in a variety of media and devices, images for deal content will be supplied in three sizes.
100x100 pixels - small
200x300 pixels - medium
440x267 pixels - large
Although it will not happen frequently, Groupon reserves the right to update image content, so API developers need to take this into consideration when applying any kind of caching of image content.
Location-Based Behavior
Where applicable, geographic information can be provided by the caller of the API in order for Groupon to respond with content for the location nearest the caller's location. This information can either be specified in geographic coordinates (latitude, longtitude), by referencing a named location, or implied based on IP address of the API request.
Latitude / Longtitude
Geographic coordinates will be accepted and understood to a precision of six decimal places or less. The nearest location will be determined relative to these coordinates.
Named Division
Deal content can be specified by naming a specific, pre-defined location (e.g. 'chicago', 'boston', etc). Currently, all divisions represent metropolitan areas (and are therefore geographic in nature). Since the list of pre-defined
IP-Based Location
As a failover, Groupon will default to determining the approximate location of the user based on the IP address of the inbound API request. The accuracy of this information varies based on changes to network topology, so this approach should only be used in cases where another method of determining or prompting for the user's location can not be implemented.