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.
  • If you are logged-in, we've pre-populated this documentation with your actual key so you can just copy and paste 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 applications that interact with the Yipit platform. You can use the API to get a list of deals near a specific latitude and longitude 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.

We are very serious about this. Please email us and we'll get right back to you.

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

All output is returned in JSON format. For more details on JSON and to obtain parsers please visit json.org. If you need XML format, please email us at api@yipit.com and we'll get back to you right away.

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/


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/379790?key=KEY_REQUIRED

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=2124134259, 2124655555
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 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=KEY_REQUIRED&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/click/?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=KEY_REQUIRED

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=KEY_REQUIRED&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=KEY_REQUIRED

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=KEY_REQUIRED&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.

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

Returns: 

    {
       "meta": {
              "code": 200
          }
       "response": {
           "tags": [
           {
                "name": "Restaurants",
                "slug": "restaurants",
                "url": ""
           },
           {
                "name": "Bar & Club",
                "slug": "bar-club",
                "url": ""
           }
    }
We have recently added high-level category tags to the API. Please note that the Tags API does not currently return these high-level category tags. This will be updated shortly. The high-level tags are listed below and a list of the underlying tags that comprise these parent tags can be found here Category Tags.

  • Activities & Adventures: 'activities-adventures'
  • Dining & Nightlife: 'dining-nightlife'
  • Fitness: 'fitness'
  • Health & Beauty: 'health-beauty'
  • Retail & Services: 'retail-services'

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=2014445555
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=KEY_REQUIRED&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 are in the early stages of building the Yipit API and 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 (seriously). For more specific inquires, please email us at api@yipit.com.