We LOVE feedback. Take our survey and give us some!

Welcome!

Welcome to the mydealbag API documentation. The intended audience are those of you with some programming abilities; don't worry, the API is simple (we hope), so you don't have to be an expert. If you are familiar with XML, you should feel right at home. If not, feel free to check out an XML tutorial; I recommend one from W3Schools.

Requirements

Most importantly, you will need an API key. If you don't have one, apply here.

Otherwise, all you need to be able to do is make GET requests to our API server: api.mydealbag.com

If you make a valid request, you will receive an XML response, but we'll get to that in a second.

GET Request Format

Every GET request will follow the following URL format:

http://api.mydealbag.com/v1/<Function>/<API key>/<Parameter 1>

For example, if your API key is 'aBcDe12345', and you would like to get the active deals in Vancouver, you would make a request to the following URL:

http://api.mydealbag.com/v1/deals/aBcDe12345/vancouver

NOTE: not all functions require parameter 1, and in some cases it will be optional

Functions

  1. CITIES: this function returns the list of supported cities.

    • Requires: Valid API Key
    • Parameter 1 (optional): 2 character country code ('US' or 'CA') if you would only like cities for the USA or Canada respectively. If omitted, all cities are returned.

    Example GET Request for cities supported in Canada:

    http://api.mydealbag.com/v1/cities/aBcDe12345/CA

    Example XML Response - NOTE: not all returned cities are displayed for brevity

    <?xml version="1.0" encoding="UTF-8"?> 
    <dealbyday> 
        <cities> 
            <city> 
                <name>Calgary</name> 
                <country>CA</country> 
                <lat>51.045</lat> 
                <lng>-114.057</lng> 
                <url-name>calgary</url-name> 
            </city> 
            .
            .
            .
        </cities>
    </dealbyday>					

    NOTES: 'url-name' shows a safe name to use in a URL sent to our API servers for those functions that require a city parameter.

  2. CATEGORIES: this function returns the list of categories used by mydealbag.

    • Requires: Valid API Key

    Example GET Request for categories used by mydealbag:

    http://api.mydealbag.com/v1/categories/aBcDe12345

    Example XML Response - NOTE: not all returned categories are displayed for brevity

    <?xml version="1.0" encoding="UTF-8"?> 
    <dealbyday> 
        <categories>
            <parent-category> 
                <name>Dining &amp; Nightlife</name> 
                <sub-categories> 
                    <sub-category> 
                        <name>Bars &amp; Clubs</name> 
                    </sub-category> 
                    <sub-category> 
                        <name>Restaurants</name> 
                    </sub-category> 
                </sub-categories> 
            </parent-category>
            .
            .
            .
        </categories>
    </dealbyday>					
  3. DEALS: this function returns the active deals for the selected city.

    • Requires: Valid API Key
    • Parameter 1: city name, as specified in the 'url-name' element in the cities response

    Example GET Request for active deals in San Jose:

    http://api.mydealbag.com/v1/deals/aBcDe12345/san-jose

    Example XML Response - NOTE: not all returned deals are displayed for brevity

    <?xml version="1.0" encoding="UTF-8"?> 
    <dealbyday> 
        <deals> 
            <deal> 
                <title>$29.99 for a Makeup Application</title> 
                <price>29.99</price> 
                <discount>85</discount> 
                <value>200</value> 
                <num-sold></num-sold> 
                <ends>2011-01-31 10:00:00 PST</ends> 
                <created>2011-01-21 15:06:09 PST</created> 
                <url>mydealbag.com/deals/10351-icoupononline-2999-for-a-makeup-application-mini-facial-manicure-pedicure-haircut-amp-style</url> 
                <image-url>http://api.mydealbag.com/image/id/10351</image-url> 
                <locations> 
                    <location> 
                        <address>123 Any St., San Jose CA 123456</address> 
                        <lat>37.3403</lat> 
                        <lng>-121.882</lng> 
                    </location> 
                </locations> 
                <categories> 
                    <sub-category> 
                        <name>Barber Shop</name> 
                    </sub-category> 
                    <sub-category> 
                        <name>Makeup</name> 
                    </sub-category> 
                    <sub-category> 
                        <name>Hair Salon</name> 
                    </sub-category> 
                    <sub-category> 
                        <name>Manicure/Pedicure</name> 
                    </sub-category> 
                    <sub-category> 
                        <name>Facial</name> 
                    </sub-category> 
                </categories> 
                <provider>
                    <name>A Deal Site</name>
                    <website>http://www.sample-deal-site.com/</website>
                </provider>
                <merchant>
                    <name>Some Spa and Salon</name>
                    <phone/>
                    <address/>
                    <email/>
                    <website>http://www.sample.com</website>
                </merchant>
            </deal> 
            .
            .
            .
        </deals>
    </dealbyday>					

    Notes:

    • If the number of sold items is unknown, 'num-sold' will be empty.
    • 'created' is when our deal crawler first indexed the deal - not necessarilly when the deal started
    • 'locations' can have 0 or more 'location' elements
    • 'categories' will have 0 or more 'sub-category' elements. To get the parent element, you will have to match it up from the response to the categories function.

Errors

If our API servers encounter a recoverable error, you will only receive an 'error' element containing an error message, for example:

<?xml version="1.0" encoding="UTF-8"?>
<dealbyday>
    <error>Invalid API key: &#39;adsfaf&#39;</error>
</dealbyday>			

What else?

That's it! We told you it was simple! Now go create some cool apps!

Still Stumped?

If you have found an error, or cannot figure the API out, contact us at api@mydealbag.com