Developer's Guide and API Documentation

» If it sounds too good to be true, it must be from Specialdeals.com to be true! And we GUARANTEE it! «

Specialdeals.com, Inc. (SDI) API Version 1.0 is now available. Our "special Deals Gifts" facebook application was built with SDI API. You can fill out the form on the right to receive your application ID / secret key and join our Affiliate Program. Your affiliate ID will be automatically appended to the link to our special deal pages so you can earn 15% commissions from the sales of our special deals.

Overview

About the SDI API
API Endpoints and Versioning
Application Key and Application Secret
Supported Protocols and Formats
Request Format
Response Format and Error Handling
Common Data Types Format

API Reference

Deals API
Cities API

Version: 1.0

About the SDI API

SDI API allows applications to interact directly with Specialdeals.com via a REST and XML-RPC API.

API Endpoints and Versioning

Currently there is only one supported version of the API - version 1. The API endpoint for version 1 is http://www.specialdeals.com/api.php. Features may be added throughout the life of a specific version of the API, that will be reflected by incrementing minor version number of the API (i.e. 1.1, 1.2 etc). But structural or semantic changes will only appear in subsequent versions. These subsequent future versions will be distinguished by another endpoints.

Application Key and Application Secret

During signing up to use the API, two 32-character strings are generated and given to the the signer. Thease are Application Key and Application Secret. An Application Key is required on all API method requests and is specified by passing a 'appkey' parameter as part of the query string, i.e. 'appkey=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'. Application Secret must not be passed publicly, and must be kept inside the application instead. It is used to sign the query string passed to the API method request. The sign algorithm is very common (used by many APIs, including Facebook, Flickr etc) and can be expressed by the following function in PHP:

function api_generate_sig($params, $secret) {
  $s = '';
  if (is_array($params)) {
    ksort($params);
    foreach ($params as $k => $v) 
      $s .= "$k=$v";
  }
  $s .= $secret;
  return md5($s);
}

I.e. an array of key-value pairs is sorted by key alphabetically, combined into k1=v1&k2=v2... string, appended with Application Secret and MD5 hash calculated with the signature as a result. The signature must be appended to the query string and passed to the API request as an additional 'sd_sig' parameter, i.e. 'sd_sig=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'.

Application Key is used on the SpecialDeals.com side to enforce rate limits on API access, for authentication (when applicable), and to gather API usage statistics.

Supported Protocols and Formats

REST protocol and XML-RPC protocols are fully supported. The required protocol is specified by passing a 'type' parameter as part of the query string, i.e. 'type=rest' or 'type=xmlrpc'.

For the REST protocol JSON and XML formats are supported. Specifying a format on any API request will return a response in that format. The required format is specified by passing a 'format' parameter as part of the query string, i.e. 'format=json' or 'format=xml'.

For the XML-RPC protocol request and response formats conform the protocol specification (http://www.xmlrpc.com/spec).

Supported Protocols and Formats

REST protocol and XML-RPC protocol are fully supported. The required protocol is specified by passing a 'type' parameter as part of the query string, i.e. 'type=rest' or 'type=xmlrpc'.

For the REST protocol, JSON and XML formats are supported. Specifying a format on any API request will return a response in that format. The required format is specified by passing a 'format' parameter as part of the query string, i.e. 'format=json' or 'format=xml'.

For the XML-RPC protocol, request and response formats conform to the protocol specification (http://www.xmlrpc.com/spec).

Request Format

Note: For all request urls below appkey and sd_sig query string parameters are not shown, for clarity. But they are still required, and you must add them for real requests, see Application Key and Application Secret section for more information

REST Protocol

For the REST protocol, API methods must be invoked via HTTP POST method. The API method to invoke is specified by passing a 'method' parameter as part of the query string. API method parameters are specified in the request body. Below is an example of a request:
Request url:

http://www.specialdeals.com/api.php?type=rest&format=json&method=deals.getListByCity

Request headers:

Content-type: application/x-www-form-urlencoded

Request body:

cityid=us_san_francisco&active=1&categoryid=on&is_special=1&offset=0&limit=0

XML-RPC Protocol

For the XML-RPC protocol requests are sent via HTTP POST method and thier format must confirm XML-RPC specification. Below is an example of a request:
Request url:

http://www.specialdeals.com/api.php?type=xmlrpc

Request headers:

Content-type: text/xml; charset=utf-8

Request body:

<methodCall>
	<methodName>deals.getListByCity</methodName>
	<params>
		<param>
			<value><string>us_san_francisco</string></value>
		</param>
		<param>
			<value><int>1</int></value>
	 	</param>
 		<param>
  			<value><int>on</int></value>
		</param>
 		<param>
  			<value><int>1</int></value>
		</param>
 		<param>
  			<value><int>0</int></value>
		</param>
 		<param>
  			<value><int>0</int></value>
		</param>
	</params>
</methodCall>

Response Format and Error Handling

HTTP error codes are not echoed in the HTTP response headers. HTTP protocol status codes must be checked directly.

REST Protocol

Succeeded HTTP request returns response body with either mandatory javascript object with root 'data' property for JSON format or root 'response' tag and 'data' subtag for XML format.

API errors are returned via response body with either mandatory javascript object with root 'errNo' property for JSON format or root 'response' tag and 'errNo' subtag for XML format.

Below is an example of succeeded API responce in JSON and XML formats:

{"data":[{"id":"splendente","requested_cityid":"us_san_francisco","is_sdotd":0,"is_fsd":0,"title":"Splendente Skin Care Special - Up to $195 of treatments for only $75","description":"Try the Interceuticals Oxygen Infusion Treatment a $195 value for $75.00 or other skin care treatments. Treatments include multiple skin peels, crystal free microdermabrasion, dermaplanning & more.... Multiple chemical peels, the Intraceuticasl oxygen Facial, eyebrow  Lara, who has been in the spa industry for 10 years. She has a unique touch in blending together clinical treatments that results in glowing skin for weeks, not just days.","category":"Health and Medical","subcategory":"Skin Care","is_on":true,"is_expired":false,"is_coming":false,"price":"75.00","currency":"USD","discount":120,"discount_percent":61.5384615385,"total_quantity_sold":0,"total_quantity_left":152,"total_quantity_sold_advanced":48,"is_sold_out":false,"has_orders_limit":true,"page_url":"http:\/\/www.specialdeals.com\/deal.php?dealid=splendente&cityid=us_san_francisco","sdotd_url":"http:\/\/www.specialdeals.com\/sdotd.php?cityid=us_san_francisco","fsd_url":"http:\/\/www.specialdeals.com\/fsd.php?cityid=us_san_francisco","image_url":"http:\/\/www.specialdeals.com\/dimages\/splendente.jpg","thumb_url":"http:\/\/www.specialdeals.com\/dimages\/splendente-thumb.jpg","discount_image_url":"http:\/\/www.specialdeals.com\/images\/61off.png"}]}

<response>
	<data>
		<array>
			<id>splendente</id>
			<requested_cityid>us_san_francisco</requested_cityid>
			<is_sdotd>0</is_sdotd>
			<is_fsd>0</is_fsd>
			<title>Splendente Skin Care Special - Up to $195 of treatments for only $75</title>
			<description>Try the Interceuticals Oxygen Infusion Treatment a $195 value for $75.00 or other skin care treatments. Treatments include multiple skin peels, crystal free microdermabrasion, dermaplanning & more.... Multiple chemical peels, the Intraceuticasl oxygen Facial, eyebrow  Lara, who has been in the spa industry for 10 years. She has a unique touch in blending together clinical treatments that results in glowing skin for weeks, not just days.</description>
			<category>Health and Medical</category>
			<subcategory>Skin Care</subcategory>
			<is_on>1</is_on>
			<is_expired></is_expired>
			<is_coming></is_coming>
			<price>75.00</price>
			<currency>USD</currency>
			<discount>120</discount>
			<discount_percent>61.5384615385</discount_percent>
			<total_quantity_sold>0</total_quantity_sold>
			<total_quantity_left>152</total_quantity_left>
			<total_quantity_sold_advanced>48</total_quantity_sold_advanced>
			<is_sold_out></is_sold_out>
			<has_orders_limit>1</has_orders_limit>
			<page_url>http://www.specialdeals.com/deal.php?dealid=splendente&cityid=us_san_francisco</page_url>
			<sdotd_url>http://www.specialdeals.com/sdotd.php?cityid=us_san_francisco</sdotd_url>
			<fsd_url>http://www.specialdeals.com/fsd.php?cityid=us_san_francisco</fsd_url>
			<image_url>http://www.specialdeals.com/dimages/splendente.jpg</image_url>
			<thumb_url>http://www.specialdeals.com/dimages/splendente-thumb.jpg</thumb_url>
			<discount_image_url>http://www.specialdeals.com/images/61off.png</discount_image_url>
		</array>
	</data>
</response>

Below is an example of error response in JSON and XML formats:

{"errNo":1024,"errStr":"Unknown method: getList"}

<response>
	<errNo>1024</errNo>
	<errStr>Unknown method: getList</errStr>
</response>

XML-RPC Protocol

For the XML-RPC protocol response format confirms XML-RPC specification. Below is an example of succeeded response:

<?xml version="1.0" encoding="iso-8859-1"?>
<methodResponse>
	<params>
		<param>
			<value>
				<array>
					<data>
						<value>
							<struct>
								<member>
									<name>id</name>
									<value><string>kravmaga-sf</string></value>
								</member>
								<member>
									<name>requested_cityid</name>
									<value><string>us_san_francisco</string></value>
								</member>
								<member>
									<name>is_sdotd</name>
									<value><int>0</int></value>
								</member>
								<member>
									<name>is_fsd</name>
									<value><int>1</int></value>
								</member>
								<member>
									<name>title</name>
									<value><string>Krav Maga SF Special - a $119 value for only $19!</string></value>
								</member>
								<member>
									<name>description</name>
									<value><string>$119 monthly membership is only $19 for the first month! Get unlimited access to all of our classes during this special one-month membership period. Good at Krav Maga San Francisco; 1455 Bush Street. Krav Mega provides unconditional support for all of our members in their journey of self improvement. To challenge our members mentally and physically in a non-judgemental and fun environment. All skill levels welcome.</string></value>
								</member>
								<member>
									<name>category</name>
									<value><string>Fitness</string></value>
								</member>
								<member>
									<name>subcategory</name>
									<value><string>Gym</string></value>
								</member>
								<member>
									<name>is_on</name>
									<value><boolean>1</boolean></value>
								</member>
								<member>
									<name>is_expired</name>
									<value><boolean>0</boolean></value>
								</member>
								<member>
									<name>is_coming</name>
									<value><boolean>0</boolean></value>
								</member>
								<member>
									<name>price</name>
									<value><string>19.00</string></value>
								</member>
								<member>
									<name>currency</name>
									<value><string>USD</string></value>
								</member>
								<member>
									<name>discount</name>
									<value><double>100</double></value>
								</member>
								<member>
									<name>discount_percent</name>
									<value><double>84.033613445378</double></value>
								</member>
								<member>
									<name>total_quantity_sold</name>
									<value><int>0</int></value>
								</member>
								<member>
									<name>total_quantity_left</name>
									<value><int>0</int></value>
								</member>
								<member>
									<name>total_quantity_sold_advanced</name>
									<value><int>42</int></value>
								</member>
								<member>
									<name>is_sold_out</name>
									<value><boolean>0</boolean></value>
								</member>
								<member>
									<name>has_orders_limit</name>
									<value><boolean>0</boolean></value>
								</member>
								<member>
									<name>page_url</name>
									<value><string>http://www.specialdeals.com/deal.php?dealid=kravmaga-sf&cityid=us_san_francisco</string></value>
								</member>
								<member>
									<name>sdotd_url</name>
									<value><string>http://www.specialdeals.com/sdotd.php?cityid=us_san_francisco</string></value>
								</member>
								<member>
									<name>fsd_url</name>
									<value><string>http://www.specialdeals.com/fsd.php?cityid=us_san_francisco</string></value>
								</member>
								<member>
									<name>image_url</name>
									<value><string>http://www.specialdeals.com/dimages/kravmaga-sf.jpg</string></value>
								</member>
								<member>
									<name>thumb_url</name>
									<value><string>http://www.specialdeals.com/dimages/kravmaga-sf-thumb.jpg</string></value>
								</member>
								<member>
									<name>discount_image_url</name>
									<value><string>http://www.specialdeals.com/images/84off.png</string></value>
								</member>
							</struct>
						</value>
					</data>
				</array>
			</value>
		</param>
	</params>
</methodResponse>

Below is an example of error response:

<?xml version="1.0" encoding="iso-8859-1"?>
<methodResponse>
	<fault>
		<value>
			<struct>
				<member>
					<name>faultCode</name>
					<value><int>-32602</int></value>
				</member>
				<member>
					<name>faultString</name>
					<value><string>server error. invalid method parameters</string></value>
				</member>
			</struct>
		</value>
	</fault>
</methodResponse>

Common Data Types Format

Dates & Times

Throughout the API, date and time are returned in ISO 8601 format. All times should be assumed to be returned in UTC.

Currency

Currency is returned as separate javascript object property or xml tag as three letter currency code (see http://en.wikipedia.org/wiki/ISO_4217 for more information).

Images

Images for deal content are supplied in two sizes.

    120x120 pixels - small
    ???x??? pixels - large (width and height are not fixed but they will be < 600 pixels)

Specialdeals.com 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.

Deals API

This section describes deals related part of API. It currently consist of deals.getTotal, deals.getListByCity, deals.getListByIds, deals.get, deals.getSdotd and deals.getFsd API methods. The deals.get API method returns a single int number, deals.getListByCity, deals.getListByIds return a list of deal structures, and finally deals.get, deals.getSdotd and deals.getFsd return a single deal structure.

Deal category structure fields:

Name	Type	Description
id	string	Human-readable but unique deal category id.
name	string	Deal category name.
is_special	string	Is the category predefined. There are 4 of predefined ('special') categories: 'coming', 'on', 'expired' and 'soldout'.
deals_count	string	Total deals count for the category.

Deal structure fields:

Name	Type	Description
id	string	Human-readable but unique deal id.
requested_cityid	string	Human-readable city id that has been passed as a parameter of API method that returned this deal. City id incorporated into deal page url (see below) may be different from requested_cityid when deal coveres several cities.
is_sdotd	int	Is the deal a Special Deal of The Day for the requested_cityid city.
is_fsd	int	Is the deal a Featured Deal for the requested_cityid city.
title	string	Deal title. Provides quick and short summary for the deal.
description	string	Deal description. Provides detailed deal description.
category	string	Deal category.
subcategory	string	Deal subcategory.
is_on	int	Is the deal currently on in the requested_cityid city.
is_expired	int	Is the deal expired in the requested_cityid city.
is_coming	int	Is the deal coming in the requested_cityid city.
currency	string	Currency for all deal money related fields.
price	double	Deal price the customer to pay.
discount	double	Deal discount from the original deal price.
discount_percent	double	Deal discount in percents.
total_quantity_sold	int	The sum of deal quantities sold.
total_quantity_left	int	Deal quantities left to be sold before the deal quantities sold limit reached (applicable if the deal has the sold limit).
has_orders_limit	int	Has the deal quantities sold limit.
is_sold_out	int	Is deal quantities sold limit reached.
page_url	string	Deal page url on the Specialdeals.com site.
image_url	string	Deal big image url.
thumb_url	string	Deal small image (thumbnail) url.
discount_image_url	string	Discount image url with the 'XX% Off' wording that corresponds to deal discount value.

deals.getCategoryList

Description:
Returns an overal list of deal categories.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=deals.getCategoryList
http://www.specialdeals.com/api.php?type=rest&format=xml&method=deals.getCategoryList

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
deals.getCategoryList

No parameters.

deals.getCategoryListByCity

Description:
Returns a list of deal categories for a specified city.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=deals.getCategoryListByCity
http://www.specialdeals.com/api.php?type=rest&format=xml&method=deals.getCategoryListByCity

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
deals.getCategoryListByCity

Parameters:

Name	Type	Description
cityid	string	Human-readable city id.
active	int	Ignored if set to 0. If set to 1, requests count (for 'deals_count' category parameter) 'active' deals only. See also the description of deals.getTotal API method.

deals.getTotal

Description:
Returns count of deals for a specified city.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=deals.getTotal
http://www.specialdeals.com/api.php?type=rest&format=xml&method=deals.getTotal

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
deals.getTotal

Parameters:

Name	Type	Description
cityid	string	Human-readable city id.
active	int	Ignored if set to 0. If set to 1, requests 'active' deals only. Some deals may not be ready to be public yet, or some deals may temporarily be made hidden, 'active' flag set to 1 will filter our all such deals.
categoryid	string	Human-readable deal category id.
is_special	int	Should the category id above be interpreted as a predefined category.

deals.getListByCity

Description:
Returns a list of deal structures for the specified city.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=deals.getListByCity
http://www.specialdeals.com/api.php?type=rest&format=xml&method=deals.getListByCity

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
deals.getListByCity

Parameters:

Name	Type	Description
cityid	string	Human-readable city id.
active	int	Same as for deals.getTotal API method.
categoryid	int	Same as for deals.getTotal API method.
is_special	int	Same as for deals.getTotal API method.
offset	int	Result deals page offset.
limit	int	Result deals page maximum size.

deals.getListByIds

Description:
Returns a list of deal structures by specified deal ids.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=deals.getListByIds
http://www.specialdeals.com/api.php?type=rest&format=xml&method=deals.getListByIds

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
deals.getListByIds

Parameters:

Name	Type	Description
ids	array of structs	List of deal ids. Each is is a struct combining human-readable city id and human-readable deal id.

deals.get

Description:
Returns a deal structure by a specified deal id.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=deals.get
http://www.specialdeals.com/api.php?type=rest&format=xml&method=deals.get

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
deals.get

Parameters:

Name	Type	Description
cityid	string	Human-readable city id.
dealid	string	Human-readable deal id.

deals.getSdotd

Description:
Returns a Special Deal of The Day deal structure for the specified city.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=deals.getSdotd
http://www.specialdeals.com/api.php?type=rest&format=xml&method=deals.getSdotd

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
deals.getSdotd

Parameters:

Name	Type	Description
cityid	string	Human-readable city id.

deals.getFsd

Description:
Returns a Featured Deal deal structure for the specified city.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=deals.getFsd
http://www.specialdeals.com/api.php?type=rest&format=xml&method=deals.getFsd

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
deals.getFsd

Parameters:

Name	Type	Description
cityid	string	Human-readable city id.

Cities API

This section describes cities related part of API. It currently consist of cities.getList and cities.getFbCityApps API methods. The cities.getList API method returns a list of city structures, while cities.getFbCityApps API method returns a list of Facebook Specialdeals.com city application description structures.
City structure fields:

Name	Type	Description
id	string	Human-readable but unique city id.
name	string	City name.
description	string	City description. Provides detailed city description.
public	int	Public flag for the city means that city's deal are available for customers.

Facebook Specialdeals.com city application description structure fields:

Name	Type	Description
cityid	string	Human-readable city id to which the Facebook Specialdeals.com city application corresponds.
cityname	string	City name.

cities.findNearestCity

Description:
Returns a supported city, which is nearest to the geographical location with latitude and longitude specified.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=cities.findNearestCity
http://www.specialdeals.com/api.php?type=rest&format=xml&method=cities.findNearestCity

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
cities.findNearestCity

Parameters:

Name	Type	Description
latitude	float	Latitude of a geographical location, in degrees. E.g. 37.7833 and -122.4333 are the latitude and longitude of San Francisco, USA.
longitude	float	Longitude of a geographical location, in degrees. E.g. 37.7833 and -122.4333 are the latitude and longitude of San Francisco, USA.
public_only	int	Ignored if set to 0. If set to 1, only public cities will be returned.

cities.getList

Description:
Returns a list of city structures.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=cities.getList
http://www.specialdeals.com/api.php?type=rest&format=xml&method=cities.getList

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
cities.getList

Parameters:

Name	Type	Description
public_only	int	Ignored if set to 0. If set to 1, only public cities will be returned.

cities.getFbCityApps

Description:
Returns a list of Facebook Specialdeals.com city application description structures.

REST urls:
http://www.specialdeals.com/api.php?type=rest&format=json&method=cities.getFbCityApps
http://www.specialdeals.com/api.php?type=rest&format=xml&method=cities.getFbCityApps

XML-RPC url:
http://www.specialdeals.com/api.php?type=xmlrpc

XML-RPC method name:
cities.getFbCityApps

No parameters.

Make Easy $$ Money from Our Special Deals

Email:
Password:
Verify Password:
Website / App URL:
App / Description: