API Documentation

Table Of Contents

The following are the major aspects of the Yipit API:


Important Notes

Please note the following:
  • Usage of this API is subject to our API Terms of Use.
  • The Yipit API is meant for consumer facing integrations.
  • If you are logged-in, we've pre-populated this documentation with your actual key so you can just copy and paste or click on the links.
  • The primary way this API is intended to be used is to search for deals using the Deals API. Searching for deals on a business by business basis is extremely unlikely to return active deals. We recommend searching for deals based on geographies (divisions or latitude/longitude with radius) and tags. That is, "restaurants" in the "new-york" division.

Overview

The Yipit API enables developers to build consumer facing applications that interact with the Yipit platform. You can use the API to get a list of deals in a division or with certain tags. All Yipit calls to the API are read only GET requests.

We are focused on expanding and improving the Yipit API and would *really* appreciate any feedback you have. Please message the discussion group or email us at api@yipit.com.

High Volume Users

If you expect to be a high volume user or have special needs, please email us at api@yipit.com and we can work on a solution that will work for your team. We are successfully integrating with several high volume users.

Formats

JSON is the default payload format.

To retrieve output as XML, append the query paramater "format=xml", or send an "application/xml" Accept Header with your request.

curl http://api.yipit.com/v1/deals/?key=[YOUR_KEY]&format=xml

curl -H "ACCEPT: application/xml" http://api.yipit.com/v1/deals/?key=[YOUR_KEY]

To retrieve JSONP from the client, attach a "callback=[mycallback]" query parameter.

$.ajax({
            type: 'GET',
            url: "http://api.yipit.com/v1/deals/?key=[YOUR_KEY]&limit=20&
            division=boston",
            dataType: 'jsonp',
            success: function (data) { alert("Success!"); },
            error: function () { alert('Uh Oh!'); },
            jsonpCallback: 'example',
            cache: false,
        });

returns:

example({
            "meta": {
                "code": 200,
                "next": "http://api.yipit.com/v1/deals/?callback=p&limit=20&
                key=[YOUR_KEY]&offset=20",
                "previous": null
            },
            "response": {
                "deals": [
                    "yipit_title": "$7 for $15 Worth of Skincare Merchandise @
                    Hawaiian Dreams Body Spa",
                    "yipit_url": "http://yipit.com/oklahoma-city/crowdsavings/7-
                    for-15-worth-of-skincare-merchandise-hawaiian-dreams-body-spa/"

                    ...more deal data...
                ]
            }
        });

Dates and Times

All datetimes are in UTC.


HTTP Path

All API methods provided in this document exist under the following path:
http://api.yipit.com/v1/

As an example, to see deals, the full url would be:
http://api.yipit.com/v1/deals/


Deal URL Types

The Yipit Deal API returns the three possible URL types to follow:

  • url
  • mobile_url
  • yipit_url

Each of these URLs redirects to the Yipit deal page; however, "mobile_url" and "yipit_url" are officially deprecated so "url" is advised in all cases.


Pagination

Results from our API endpoints are paginated and the default page size varies on a per resource basis. To define the desired page size per request, attach a "limit=n" query param along with an (optional) "offset=n" param.

curl http://api.yipit.com/v1/deals/?key=[YOUR_KEY]&limit=5&offset=10


API Key

All API calls require an API Key. Please visit API Request to register for your API key which will provide you with access. You will use this API key as the key parameter.


Common API Parameters

The following parameters are used across all API requests:

NameRequiredDescriptionExample
key required An api key, allowing you access to the Yipit API. key=API_KEY

The Meta Object

Every response contains meta object with a status code.

  • All properly processed requests will return a code of 200
  • See Error Codes below for more details.

Error Codes

In the case that the Yipit API encounters one of the errors below, the API will set the applicable HTTP status code and return the error object below.

For example, if an incorrect key is provided, the following error json object will be returned with an HTTP status code of 401.

        {
            "meta": {
                "message": "Key not recognized",
                "code": 401,
                "name": "AuthenticationFailed"
            },
            "response": {}
        }

Possible error code values:

  • 400 : Invalid Request (Bad or missing parameters)
  • 401 : Authentication Error Unauthorized
  • 404 : Named resource not found
  • 500 : Internal Service error -- Please post to the group or email api@yipit.com so that the Yipit team can investigate
  • 502 : Bad Gateway -- Yipit is down or is being upgraded. Try again later.

Deals API

Users can request deals in one of two ways:

Requesting a deal by deal_id

Path:
/deals/[<deal_id>]

This method returns the deal with id <deal_id> or 404.

Sample Request:
http://api.yipit.com/v1/deals/79192?key=YIPIT_KEY

Requesting deals by parameters:

Path:
/deals/?p1=v1&p2=v2

This method returns a list of deals filtered by the parameters provided, if any.

The following are possible parameters (in addition to the common API parameters):
Please note that all boolean values can be specified as either: {1, true, True} for TRUE or {0, false, False} for FALSE.

NameRequiredDescriptionExample
lat lon optional Latitude and longitude of point to sort deals by proximity to. Uses radius. lat=-37.74&lon=-76.00
radius optional Maximum distance of radius in miles to deal location from center point. Defaults to 10. Requires lat and lon lat=-37.74&lon=-76.00&radius=1.7
division optional One or more division slugs (comma separated). See Divisions API for more details. division=new-york,atlanta
source optional One or more source slugs (comma separated). See Sources API for more details. source=groupon, scoutmob
phone optional Deals available at a business matching one of the phone numbers. See Businesses API for more details. phone=212-413-4259, 212-465-5555
tag optional One or more tag slugs (comma separated). See Tags API for more details. Note: Specifying multiple tags returns deals matching any one of the tags, NOT all of them. Update: we have exposed high level category slugs that can be used interchangeably with tag slugs (category slugs are supersets of tag slugs). A list of category slugs can be found here. tag=restaurants,spa
paid optional Shows deals filtered on paid status. Defaults to: {0, false, False} which shows all deals. Set to: {1, true, True} to show only deals from paid sources. See Affiliate Programs for more details. paid=1
paid=true
paid=True
limit optional Maximum number of items returned. Default 20. Max 5000. limit=300

Sample Request:
http://api.yipit.com/v1/deals/?key=YIPIT_KEY&division=new-york

Returns:

    {
        "meta": {
            "code": 200
        },
        "response": {
            "deals": [
                {
                    "id": 32373,
                    "date_added": "2011-01-13 12:12:50",
                    "end_date": "2011-01-14 10:00:00",
                    "active": 1,
                    "discount": {
                        "raw": 71,
                        "formatted": "71%"
                    },
                    "price": {
                        "raw": "85.00",
                        "formatted": "$85"
                    },
                    "value": {
                        "raw": "300.00",
                        "formatted": "$300"
                    },
                    "title": "$85 For $300 Babyface Facial At Park Avenue MedSpa",
                    "yipit_title": "71% off Babyface Facial",
                    "url": "http://yipit.com/aff/eval/deal/?deal=AvwTADtE&
                    key=F374EFbM",
                    "yipit_url": "http://yipit.com/new-york/livingsocial/85-for-
                    300-babyface-facial-at-park-avenue-medspa/",
                    "mobile_url": "http://m.yipit.com/new-york/livingsocial/85-
                    for-300-babyface-facial-at-park-avenue-medspa/",
                    "images": {
                        "image_big": "http://a.cdn.yipit.com/deal_images/deal/85-
                        for-300-babyface-facial-at-park-avenue-medspa-1294920769_
                        display_image.jpg",
                        "image_small": "http://f.cdn.yipit.com/deal_images/deal/
                        85-for-300-babyface-facial-at-park-avenue-medspa-
                        1294920769_small_image.jpg"
                    },
                    "division": {
                        "slug": "new-york",
                        "name": "New York",
                        "active": 1,
                        "time_zone_diff": -4,
                        "lat": "40.7142690000000000",
                        "lon": "-74.0059730000000000",
                        "url": "http://yipit.com/new-york/"
                    },
                    "tags": [
                        {
                            "name": "Facial",
                            "slug": "facial",
                            "url": "http://yipit.com/new-york/deals/facial/"
                        },
                        {
                            "name": "Spa",
                            "slug": "spa",
                            "url": "http://yipit.com/new-york/deals/spa/"
                        }
                    ],
                    "business": {
                        "name": "Park Avenue MedSpa",
                        "url": "",
                        "locations": [
                            {
                                "address": "565 Park Ave",
                               "locality": "New York",
                                "phone": "212-593-8821",
                                "lat": null,
                                "lon": null,
                                "state": NY,
                                "zip_code": "11211"
                            }
                        ]
                    },
                    "source": {
                        "name": "LivingSocial",
                        "slug": "livingsocial",
                        "paid": 0,
                        "url": "http://yipit.com/new-york/livingsocial"
                    }
                }
            ]
        }
    }


Sources API

Users can request sources in one of two ways:

Requesting a source by source_slug:

Path:
/sources/[<source_slug>]

This method returns the source with the slug or 404.

Sample Request:
http://api.yipit.com/v1/sources/groupon?key=YIPIT_KEY

Returns:

    {
       "meta": {
          "code": 200
       }
       "response": {
          "sources": [ {
              "name": "Groupon",
              "slug": "groupon",
              "paid": 0,
              "url": ""
          } ]
      }
    }

Requesting a source by parameters:

Path:
/sources?p1=v1&p2=v2

This method returns a list of all Yipit sources filtered by the parameters provided, if any.

Input Parameters (in addition to the common API parameters):

NameRequiredDescriptionExample
division optional One or more division slugs. See Divisions API for more details. Note: Specifying multiple divisions returns sources that exist in either of the divisions, NOT all of them. division=new-york,atlanta
paid optional When paid is {1, true, True}, only paid sources are returned. Defaults to: {0, false, False}. paid=1
paid=true
paid=True
limit optional Maximum number of items returned. Default 20. Max 1000. limit=300

Sample Request:
http://api.yipit.com/v1/sources/?key=YIPIT_KEY&division=new-york,atlanta

Returns:

    {
      "meta": {
        "code": 200
      }
      "response": {
        "sources": [
        {
           "name": "1 Sale a Day"
           "slug": "1-sale-a-day"
           "paid": 0
           "url": ""
        },
        {
           "name": "Groupon"
           "slug": "groupon"
           "paid": 1
           "url": ""
        },
        {
           "name": "ScoutMob"
           "slug": "scoutmob"
           "paid": 0
           "url": ""
        }
    }


Divisions API

Users can request divisions in one of two ways:

Requesting divisions by division_slug

Path:
/divisions/[<division_slug>]

This method returns the division with the slug or 404.

Sample Request:
http://api.yipit.com/v1/divisions/new-york?key=YIPIT_KEY

Returns:

    {
      "meta": {
          "code": 200
      }
      "response": {
          "divisions": [
          {
              "slug": "new-york",
              "name": "New York",
              "active": 1,
              "time_zone_diff": -4,
              "lat": "40.7142690000000000",
              "lon": "-74.0059730000000000",
              "url": "http://yipit.com/new-york/"
         } ]
      }
    }

Requesting a division by parameters:

Path:
/divisions?p1=v1&p2=v2

This method returns a list of all divisions filtered by the parameters provided, if any.

Input Parameters:

NameRequiredDescriptionExample
source optional One or more source slugs. See Sources API for more details. Note: Specifying multiple sources returns divisions that exist in either of the sources, NOT all of them. source=groupon,scoutmob
lat lon optional Latitude and longitude of point to sort divisions. Uses radius. lat=-37.74&lon=-76.00
radius optional Maximum distance of radius in miles to division from center point. Requires lat and lon lat=-37.74&lon=-76.00&radius=1.7
limit optional Maximum number of items returned. Default 20. Max 200. limit=100

Sample Request:
http://api.yipit.com/v1/divisions/?key=YIPIT_KEY&source=groupon

Returns:

    {
      "meta": {
          "code": 200
      }
      "response": {
          "divisions": [
          {
              "slug": "atlanta",
              "name": "Atlanta",
              "active": 1,
              "time_zone_diff": -4,
              "lat": "33.7489950000000000",
              "lon": "-84.3879820000000000",
              "url": "http://yipit.com/atlanta/"
          },
          {
              "slug": "boston",
              "name": "Boston",
              "active": 1,
              "time_zone_diff": -4,
              "lat": "42.3584310000000000",
              "lon": "-71.0597730000000000",
              "url": "http://yipit.com/boston/"
        }
    }


Tags API

Requesting a list of tags:

Path:
/tags

This method returns a list of all tags. There are no parameters specific to tags.

Note: High level categories are not currently returned using this method though they are exposed through the API and can be used interchangeably with tag slugs (category slugs are supersets of tag slugs). A list of category slugs can be found here.

Sample Request:
http://api.yipit.com/v1/tags/?key=YIPIT_KEY

Returns:

    {
       "meta": {
              "code": 200
          }
       "response": {
           "tags": [
           {
                "name": "Restaurants",
                "slug": "restaurants",
                "url": ""
           },
           {
                "name": "Bar & Club",
                "slug": "bar-club",
                "url": ""
           }
    }


Businesses API

Note: The Businesses API has not yet been fully implemented. The Businesses API is intended to be used to look up businesses. If you want to find deals for a specific business, please use the Deals API and supply a phone number parameter.

Requesting a business by parameters

Path:
/businesses?p1=v1&p2=v2

This method returns a list of businesses filtered by the parameters provided, if any.

Input Parameters: (in addition to the common API parameters)

NameRequiredDescriptionExample
lat lon optional Latitude and longitude of point to to sort deals by proximity to. Uses radius. lat=-37.74&lon=-76.00
radius optional Maximum distance of radius in miles to deal location from center point. Defaults to 10. Requires lat and lon lat=-37.74&lon=-76.00&radius=1.7
phone optional Phone number of the business phone=201-444-5555
division optional One or more division slugs. See Divisions API for more details. Note: Specifying multiple divisions returns businesses that exist in either of of the divisions, NOT all of them. division=new-york,atlanta

Sample Request:
http://api.yipit.com/v1/businesses/?key=YIPIT_KEY&division=new-york

Returns:

    {
       "meta": {
              "code": 200
          }
       "response": {
           "businesses": [
                {
                    "id": 18005,
                    "name": "Orpheum Theatre  ",
                    "url": "http://orpheum-theater.com/",
                    "locations": [
                        {
                            "id": 19185,
                            "address": "126 2nd Ave.",
                            "locality": "New York",
                            "phone": "212-477-2477",
                            "lat": 40.728293800000003,
                            "lon": -73.987701900000005
                        },
                        {
                            "id": 28454,
                            "address": "126 2nd Ave",
                            "locality": "New York",
                            "phone": null,
                            "lat": 40.728293800000003,
                            "lon": -73.987701900000005
                        },
                        {
                            "id": 38495,
                            "address": "126 2nd Ave",
                            "locality": "New York",
                            "phone": null,
                            "lat": 40.728293800000003,
                            "lon": -73.987701900000005
                        }
                    ]
                }
          ]
        }
    }


Didn't See What You Were Looking For?

We will be augmenting the API continuously. For any general questions, concerns, or problems regarding the Yipit API, please leave a message on this group's discussion forum, and we'll get back to you right away. For more specific inquires, please email us at api@yipit.com.