CityDeals Logo

Stay Connected:
0 items: 0.00
Your Savings: 0.00
Hundreds of Local Deals. All Day. Every Day. API


 Sign Up For a API Key: Link

 Use Builder Form Here: Link


___ Simple API

 Last updated: 2011-06-28 1:46 PM MST

Table of Contents




The Simple API provides a mechanism for getting current deal information. The Simple API allows applications to get this information via a REST API.


All API requests must have a valid API key. This can be sent as a “token” parameter (e.g. “token=my-api-token”), or via a X-CityDeals-Token HTTP header. Requests that are denied because of rate limiting will return a 503 HTTP status code.


To acquire an API key, go to and follow the directions.

Passing Parameters

Parameters are accepted via GET or POST, unless otherwise specified. URL length should be kept in mind when passing parameters via GET.

Response Format

Responses may be returned in JSON or XML formats. The default is currently JSON. The response format may be explicitly specified in two ways. First, a “format” parameter may be passed. The second method is to append a file extension to the API method name. The examples in this section show sample URLs.


When a JSON response is requested, an additional “callback” parameter may be used to trigger the use of JSONP. This is necessary when calling this service via AJAX from your application to get around cross-domain AJAX restrictions imposed by the browser.


Sample responses shown in this document have been formatted for human-readability. When given by the API, they will not have this extra formatting. Samples shown in this document are examples of a successfully processed request, unless otherwise noted.



Response Codes

The following response codes may be generated by the API.

  1. NONE: 0
  4. NO_KEY: 201
  5. INVALID_KEY: 202
  7. AUTH_FAILURE: 300
  8. SESSION_SAVE: 301
  11. INVALID_ZONE: 500
  13. GENERIC_ERROR: 999

Data Formats

Most data returned by the API will be in simple numeric or string format. Certain data types, however will have specific formatting, as specified in this section.

Dates and Times

Date and time values will be in ISO 8601 format (


  1. Date only: 2010-12-21
  2. Date and Time: 2010-12-21T14:51:42+0:00


Currencies will be represented as a decimal value followed by a three-letter currency code (See No additional formatting will be used for values greater than 1000.


  1. 5.00USD
  2. 1000.50USD

Deals API

The Deals API provides information on available deals.


The deals API is available via 2 different URL forms:


It is recommended that form #1 is used when possible. URL form #2 exists primarily for compatibility with existing APIs.

Supported Parameters

The following parameters may be used when calling the API via URL #1 above.        

  1. zip: Zip code in which to look for deals. This behaves as if a user had typed this zip code into the search form on the website. City,State is also an accepted parameter.
  2. lat/lng: Performs a look-up of the specified latitude and longitude and uses the nearest zip code to perform a search for deals. If using either of these parameters, the other must also be passed.
  1. lat: Latitude
  2. lng: Longitude

When calling the API via URL #2, no parameters are required. When using either URL form, the optional parameters listed below may be used, if desired.

  1. q: Keywords to search for. Should be URL-encoded.
  2. range: Distance, in miles, from the center of the specified (explicitly or implicitly) zip code. Default: 10.
  3. p: If set to 1, only return deals that can be printed at home. If set to 0, return both printable and mailable deals. Default: 0.
  4. category: the merchants associated category. Default is unset and returns all category results.
  5. per_page: number of results to show per page. Default is all.
  6. current: current page in result set. Default unset.


* Response will return the total number of pages calculated on the per_page criteria, if per_page is not passed the API will default to 1 as total_pages. This can be viewed in the sample deal response data in this document.

Deal Fields

id: Unique identifier for the deal. May contain only alphanumerics and ‘-’. White space is not allowed.

deal_url: URL where the deal can be found on the website.

title: Name or short description of the deal.

sku: SKU of the product.

small_image_url: URL of deal-related image. Size is not necessarily relevant.

medium_image_url: URL of deal-related image. Size is not necessarily relevant.

large_image_url: URL of deal-related image. Size is not necessarily relevant.

national_brand: returns 0 or 1

online_brand: returns 0 or 1

division_id: Unique identifier for the division. May contain only alphanumerics and ‘-’. White space is not allowed.

division_name: Human-readable name of the division the deal is in.

division_lat: Latitude coordinate for division the deal is in. if applicable. Non-geographic divisions may not have a value for this field

division_lng: Longitude coordinate for division the deal is in if applicable. Non-geographic divisions may not have a value for this field.

division_timezone: Time zone for division the deal is in, if applicable. Non-geographic divisions may not have a value for this field.

division_offset_gmt: Time zone offset in seconds for division the deal is in, if applicable. Non-geographic divisions may not have a value for this field.

locations: Locations refer to physical locations of the business. If no location data is available for the deal, the locations element will be empty. Each child of the locations element will contain some or all of the following values:

  1. address: Street address
  2. address2: Street address line 2
  3. city: Street address city
  4. state: Street address state
  5. zip: Street address zip code
  6. lat: Latitude coordinate
  7. lng: Longitude coordinate

vendor_id: Unique identifier for the business. May contain only alphanumerics and ‘-’. White space is not allowed.

shipping_method: Returns available shipping method. response - print,mail,print-or-mail.

print products will return necessary redemption information through the Order API. Mail products will be fulfilled through the fulfillment house upon successful order.

categories: List of category information associated to the deal returned.

vendor_name: Name of the business.

vendor_listing_url: URL to the vendor’s listing on the website.

vendor_website_url: Vendor’s website address, if available.

vendor_logo: URL to vendor’s logo.

vendor_description: returns description of the merchant.

status: “open” if the deal is available for purchase, or “closed” otherwise.

start_date: Date the deal went live.

end_date: null,

tipped: Exists for compatibility. Always true.

tipping_point: Exists for compatibility. Always 0.

tipped_date: Exists for compatibility. Always same as start_date.

sold_out: True if the deal is sold out, false otherwise.

quantity_sold: Exists for compatibility. Always 0.

price: Price of the deal

value: Face value of the deal, if available.

discount_amount: Difference between value and price.

discount_percent: Difference between value and price, in percent. Equivalent to (value - price) / value * 100.

conditions: Container for deal conditions. Fields below are members of this container.

limited_quantity: Exists for compatibility and future expansion. Currently, this will always be true.

initial_quantity: Exists for compatibility and future expansion. Currently, this will always be 0.

quantity_remaining: Quantity remaining  in-stock

minimum_purchase: Minimum number that may be purchased.

maximum_purchase: Maximum number that may be purchased.

expiration_date: Date the certificate/gift card/etc expires, if available.

details: Array of details of the deal. Depending on the deal type, this may have one detail per entry, or free-form text containing all details in one entry.


Image fields may not be populated if the deal’s location does not have associated images.

Sample Responses



    “total_results”: 56,


    "status": {

        "code": 0,

        "message": "OK"


    "deals": [


            "id": "5859",

            "deal_url": "http:\/\/\/25-gift-certificate-deal.html",

            "title": "$25 Gift Certificate",

            "sku": "48614",

            "small_image_url": "",

            "medium_image_url": "",

            "large_image_url": "",

        "national_brand": 0,

        "online_brand": 1,

            "division_id": "36586",

            "division_name": "UT - Bluffdale West Jordan",

            "division_lat": "40.5967",

            "division_lng": "-112.001",

            "division_timezone": "America\/Boise",

            "division_offset_gmt": -25200,

            "locations": [


                    "address": "123 Fake Street",

                    "city": "West Jordan",

                    "state": "UT",

                    "zip": "84088",

                    "lat": "40.6068",

                    "lng": "-111.939"











"created_time":"2010-12-09 21:17:04",




            "vendor_id": "3909",

            "vendor_name": "Joe's Tea Shop",

            "vendor_listing_url":            "http:\/\/\/deals-merchant-joes-tea-west-jordan-ut.html",

            "vendor_website_url": "",

            "vendor_logo": null,

        “vendor_description”:The best tea this side of the Mississippi.

            "status": "open",

            "start_date": "2010-12-22T05:38:09+00:00",

            "end_date": null,

            "tipped": true,

            "tipping_point": 0,

            "tipped_date": "2010-12-22T05:38:09+00:00",

            "sold_out": false,

            "quantity_sold": 0,

            "price": "15.00USD",

            "value": "25.00USD",

            "discount_amount": "10.00USD",

            "discount_percent": 40,

            "conditions": {

                "limited_quantity": true,

                "initial_quantity": 0,

                "quantity_remaining": "44",

                "minimum_purchase": "1",

                "maximum_purchase": "0",

                "expiration_date": null,

                "details": [

                    "Detail line 1",

                    "Detail line 2"







<?xml version="1.0"?>

<response total_pages = “3” total_results = “56” code="0" message="OK">





      <title>$25 Gift Certificate</title>








      <division_name>UT - Bluffdale West Jordan</division_name>







          <address>123 Fake Street</address>

          <city>West Jordan</city>















<created_time>2010-06-09 17:47:56</created_time>





      <vendor_name>Joe's Tea Shop</vendor_name>




     <vendor_description>The best tea this side of the Mississippi</vendor_description>





















          <detail>Detail line 1</detail>

          <detail>Detail line 2</detail>







Non-developers may wish to use a simple implementation that they can be pasted into their own site. A simple builder is available at This can be used to generate HTML and JavaScript code that can be included on your website to retrieve and show a list of deals.


The Builder’s fields are explained below:


API Key: String containing your own API key.

Keywords: If you only want to show deals that match certain key words, use them here. Typing the same keywords in the search form on the website would get you similar results as those that will be returned by the API.

Zip Code: Zip code in which to search for deals.

Range: Number of miles from the specified zip code in which to find deals.

Show Vendor Logos: If true, each deal will have its vendor’s logo included in the output (if available). If false, the logo will not be included.

Maximum number of deals: Limit the number of deals shown. Fewer deals may be returned if there aren’t enough matches.

I already use jQuery: If you already use jQuery on the page you will be placing the generated code, check this box. This will ensure that jQuery is not included multiple times.

jQuery variable: If the “I already use jQuery” box is checked above, and you use some variable name other than the default “$”, you may specify that variable name here. This may be necessary, for example, if you are using jQuery’s “noConflict” functionality. If unsure, leave blank.


Output from the Builder will include two blocks of code that you should paste into the code for your website. The first is a container element that will be populated with the deal content. The second is a block of JavaScript and HTML that actually fetches the deal data and prepares the content for the page. These two blocks may be placed together if desired, but for performance reasons, it is recommended that the second code block be placed near the end of your page’s HTML (as near as possible to the closing “body” tag).

Divisions API

The divisions API provides a list of zones currently supported. This can be used in conjunction with the Deals API to get deals for a particular zone instead of for a specified geographical location. Divisions may or may not refer to geographical groupings.


Sample Responses



    "status": {

        "code": 0,

        "message": "OK"


    "divisions": [


            "id": "ut-downtownfoothill",

            "name": "UT - Downtown Foothill",

            "location": {

                "latitude": "40.7564",

                "longitude": "-111.899",

                "timezone": "America/Boise",

                "timezone_offset_gmt": -25200




            "id": "nationaldma",

            "name": "national dma",

            "location": {

                "latitude": "40.8131",

                "longitude": "-73.0464",

                "timezone": "America/New_York",

                "timezone_offset_gmt": -18000




            "id": "slcdma",

            "name": "slc dma",

            "location": {

                "latitude": "40.388",

                "longitude": "-111.851",

                "timezone": "America/Boise",

                "timezone_offset_gmt": -25200






<?xml version="1.0"?>

<response code="0" message="OK">




      <name>UT - Downtown Foothill</name>










      <name>national dma</name>










      <name>slc dma</name>










Authentication API

The “authenticate” method provides the ability to authenticate a user. Upon successful authentication, a session ID is returned that is tied to the authenticated user. Currently, only the “order” method accepts this session ID.


Supported Parameters

  1. email: base64 encoded email address
  2. password: base64 encoded password

Sample Responses



    "status": {

        "code": 0,

        "message": "OK"


    "session": {

        "token": "0796057fbcf809a4812e0ce79493e013"




<?xml version="1.0"?>

<response code="0" message="OK">





Signup API

The signup method allows for the creation of a user account via the API. This account can then be used for authentication and other operations via the API and via the website.


Supported Parameters

  1. email: base64 encoded email address
  2. password: base64 encoded password
  3. fname: base64 encoded first name
  4. lname: base64 encoded last name

Sample Responses



    "status": {

        "code": 0,

        "message": "OK"


    "user": {

        "id": "99999"




<?xml version="1.0"?>

<response code="0" message="OK">





Order API

The order method allows applications to place a order via the API. Currently, only “printable” products can be ordered via this method.


This method is only available if it is allowed for your API key.


Supported Parameters

  1. session: Session token returned by the “authenticate” method
  2. [billing or shipping]_*: billing/shipping address fields. If not specified, the customer’s default billing address will be used, if available.
  1. _firstname
  2. _lastname
  3. _address
  4. _city
  5. _region_id: a valid region id e.g. 58 for utah
  6. _postcode: zip code or postal code
  7. _country_id: 2-letter country code e.g. US
  8. _telephone
  9. _fax
  1. shipping_same_as_billing: boolean
  2. items: Array of product SKUs and quantities in the following format:

{“sku: 45897, “qty”: 3, “is_print”: 1 }


  1. coupon_code: the coupon code being applied to the order
  2. shipping_method: [tablerate_bestway or customerpickup_customerpickup], only required if one items are not all being printed at home.
  3. cc_type: one of [AE, VI, MC, DC] - must line up with the card number
  4. cc_number: valid credit card number
  5. cc_exp_month: integer of month e.g. 6
  6. cc_exp_year: 4 digit month e.g. 2017
  7. cc_cid: CCV number

Sample Responses



    "status": {

        "code": 0,

        "message": "OK"


    “orderId”: 1313883



If there was an error in any stage of the order processing you will receive:


    “status”: {

        “code”: 999,

        “message”: “Item not available”


    response: <full json response from the internal request>,

    action: <the internal action that was attempted e.g. savePayment,

    data: <json object containing the params sent w/ attempted action>


Category API

The category method allows applications to retrieve the top level category list via the API.

Return is key=>values, returning: category id => category name


This method is only available when providing your API key passed as the token variable.



Required Parameters


Sample Response








"1132":"Spa & Salons",


"1096":"Hotels & Travel",


"1098":"Deal Outlet",


"1324":"Print at Home"




Coupon API

The coupon API allows you to determine if a coupon is valid. If the coupon is valid it also provides the details of the coupon.



Supported Parameters

The following parameters may be used when calling the API:


coupon_code: The coupon code you are attempting to verify. If the coupon exists the “coupon” property will contain details pertaining to it regardless if it is expired (and thus not valid). If the coupon does not exist at all “coupon” will be false as well as “valid” being false.

Sample Responses



    "status": {

        "code" :0,

        "message": "OK"


    "valid": true,

    "coupon": {

        "id": "26286",

        "code": "CHOC",

        "expiresOn": "2011-07-07",

        “expired”: false,

        "discountAmount": "10.0000",

        “discountQty” => 1