1. Lexington

Home

RoyBoyDeals API

Version: 1.0

About the RoyBoyDeals API

The goal of this API is to allow applications to directly interact with RoyBoyDeals 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://royboydeals.com/newyork/deals.xml
   http://royboydeals.com/newyork/deals.xml
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, RoyBoyDeals 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 RoyBoyDeals 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, RoyBoyDeals 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.

Deals API

Retrieving Featured Deal


URL:
    http://royboydeals.com/newyork/deals.json

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 RoyBoyDeals site.  This would be the same URL a user would enter to access the deal in a web browser.
    Example: http://royboydeals.com/deal/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://royboydeals.com/img/medium_big_thumb/Deal/0.a5522c7c3f8b1a86fbd764dcad1cf216.jpg
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.  RoyBoyDeals 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 RoyBoyDeals.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 RoyBoyDeals.  This is effectively the full value of the RoyBoyDeals 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: RoyBoyDeals 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://royboydeals.com/deals/green-door-tavern/",
      "title": "$10 for $25 Worth of Food and Drink at Green Door Tavern",
      "small_image_url": "http://royboydeals.com/img/small_thumb/Deal/0.a5522c7c3f8b1a86fbd764dcad1cf216.jpg",
      "medium_image_url": "http://royboydeals.com/img/small_big_thumb/Deal/0.a5522c7c3f8b1a86fbd764dcad1cf216.jpg",
      "large_image_url": "http://royboydeals.com/img/medium_big_thumb/Deal/0.a5522c7c3f8b1a86fbd764dcad1cf216.jpg",
      "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"
        ]
      }