-
Notifications
You must be signed in to change notification settings - Fork 0
DealNews Public API
The DealNews API is a RESTish style web service. Wikipedia has a nice writeup on REST. A key aspect of a REST web service is the concept of resources with uniquely defined URIs. The DealNews API includes several such resources and all are available from the base endpoint:
https://api.dealnews.com
Note that all API requests must use HTTPS.
In this document, all resource paths are assumed to be referenced from the base endpoint.
There are two distinct types of resources that are available in the API. First there are Content resources such as deals, coupons and feature articles. Second there are Ancillary resources that consists of stores, categories and brands. Below the top-level resources may be sub-resources allowing for related data to be returned. For example, one can retrieve the list of stores corresponding to the results from a /deals call by simply calling /deals/stores.
The only HTTP verb supported is GET. POST, PUT and DELETE are not supported.
An API key is required for access to the DealNews API. This API key is provided by DealNews and must be present in the Authorization header as shown in the example below:
Authorization: DN your-api-key-here
The desired format of the returned API results is specified by providing a Content-Accept header. If this header is not specified, the results will be returned as JSON. Acceptable formats are JSON and XML, thus valid headers are:
Content-Accept: application/json
or
Content-Accept: application/xml
Note that the output data formats described in this document should be considered the authoritative description of the data that is returned by the API. Any data that is returned in API calls that is not included in this document should be considered experimental and/or deprecated and should not be used. Please contact your DealNews account representative for more information.
Along with your API key, DealNews will also provide to you a unique referral code which we refer to as a REFCODE. This REFCODE is included in result URLs which allow you to receive credit for clicks.
Previous versions of the DealNews API required your REFCODE to be present on the query string of every API call. The new API's API key negates this requirement so your REFCODE is no longer necessary to be provided in API calls.
DealNews allows for customization of your referral code by appending a hyphen and an alphanumeric string to your REFCODE and the fully customized REFCODE will be provided in the result URLs. For example a REFCODE of 'myrefcode' can be customized as 'myrefcode-01' or 'myrefcode-sidebar'. One application of REFCODE customization is for a revenue performance comparison of DealNews content provided in different regions of a website. Another application is for tracking results from different categories or stores. All DealNews API calls accept a "refcode" parameter in the query string and custom REFCODEs should be the value of that parameter. Please note that the base of the customized REFCODE must match exactly the one DealNews provided to you. Furthermore, the customization must follow a single hyphen and can only consist of alpha-numeric characters (a-z, A-Z and 0-9).
All responses will provide an indication of the success or failure of the API call. If the API call is successful, a JSON status => success key-value pair or an XML status node with a value=success attribute will be provided alongside the actual results. If the API call was unsuccessful, additional information will be provided explaining the error. For example, if you fail to provide an authentication header with your API key, the following error will be thrown:
{
status: "fatal_error",
code: 4,
message: "Missing Authentication header."
}
or, in XML:
<status value="fatal_error" code="4" message="Missing Authentication header." />
The following inputs can be provided on the query string for any API call
| Key | Type | Default | Description |
|---|---|---|---|
| refcode | string | none | All content links will be tagged with the REFCODE provided. If no REFCODE is given, all content links will be tagged with your default REFCODE. |
| limit | integer | varies | Limit the number of returned items to the value specified. A maximum limit is enforced and will be the default limit if one is not provided. The maximum varies depending on the API resource being requested. |
| start | integer | 0 | For datasets with a number of items that exceed the limit, use this value to retrieve the next set of results. |
Regardless of the API call made, there is a common organizational structure for the results. When a list of content is returned, it is contained within a dataset. Within the dataset and alongside the content are fields which describe the dataset and possibly a list of related resources.
For example, when a call to deals is made, the result structure looks like the following for JSON:
{
status: "success"
datasets: [
{
dataset_name: "articles",
dataset_type: "array",
articles_found: 1043,
articles_returned: 100,
resources: [
{
url: "https://api.dealnews.com/deals",
title: "Start of results",
description: "Results from 1 to 100",
tag: "array_start"
},
{
url: "https://api.dealnews.com/deals?start=201&limit=100",
title: "Next set of results",
description: "Results from 201 to 300",
tag: "array_next"
},
{
url: "https://api.dealnews.com/deals/stores",
title: "Related Stores",
description: "List of stores for articles found",
tag: "related_stores"
},
{
url: "https://api.dealnews.com/deals/categories",
title: "Related Categories",
description: "List of categories for articles found",
tag: "related_categories"
},
{
url: "https://api.dealnews.com/deals/brands",
title: "Related Brands",
description: "List of brands for articles found",
tag: "related_brands"
}
],
articles: [
{
id: 591410,
title: "30 Shark EuroPro Space Saving Hangers w/ 4 Stain Guards for $5 + $5 s&h"
...
},
...
]
}
]
}
Note that the datasets object is an array. Some resources can return more than one dataset.
A call to the base endpoint will result in a list of all top-level resources that are available.
{
status: "success"
resources: [
{
url: "https://api.dealnews.com/deals",
title: "Current Deals",
description: "Recent deals that are still active",
tag: "deals"
},
{
url: "https://api.dealnews.com/coupons",
title: "Current Coupons",
description: "Recent coupons that are still active",
tag: "coupons"
},
{
url: "https://api.dealnews.com/features",
title: "Feature Articles",
description: "Where our readers go for more in-depth price trend information, buying advice, reviews, humor, and more",
tag: "features"
},
{
url: "https://api.dealnews.com/blackfriday",
title: "Black Friday Ads",
description: "Black Friday Ads",
tag: "blackfriday"
},
{
url: "https://api.dealnews.com/stores",
title: "Store List",
description: "Complete list of stores",
tag: "stores"
},
{
url: "https://api.dealnews.com/categories",
title: "Category List",
description: "Complete list of categories",
tag: "categories"
},
{
url: "https://api.dealnews.com/brands",
title: "Brand List",
description: "Complete list of brands",
tag: "brands"
}
]
}
The structure of the deals resource is as follows:
/deals
/today
/edition/<YYYY-MM-DD>
/choice
/search
The following inputs are valid for a /deals call
| Key | Type | Default | Description |
|---|---|---|---|
| sort | string | first_publish_time | This value specifies how the returned content is sorted. The valid sort values are hotness, first_publish_time, latest_publish_time and price. |
| promoted | integer | 0 | If a non-zero value is specified, then promoted content will be included in any data that is returned. |
| editors_choice | integer | unset | This is a tri-state variable. If the parameter is not specified in the query string, Editor's Choice deals will be included in the results. If the value is 0, no Editor's Choice deals will be included in the results. If the value is 1, only Editor's Choice deals will be returned. |
| ended | integer | 0 | If non-zero, deals that no longer show up on the dealnews.com front page will be included in the results. |
| hotness | integer | 0 | If non-zero, only deals with a hotness greater than the value specified will be returned. |
- The default number of deals returned in a call is 30
- The maximum value of the limit parameter is 250
All deals are formatted like so:
{
content_type: "ARTICLE",
id: 1026582,
title: "Scotts 2-lb. Plant Food for $0 after rebate + pickup at Home Depot",
brief_title: "Scotts 2-lb. Smart-Release Plant Food $0",
description_html: "...",
description_text: "...",
link: "...",
short_link: "...",
buy_now_link: "...",
pub_date: "Fri, 11 Apr 2014 11:18:01 -0400",
updated: "3 min ago",
promoted: 0,
expires: "Mon, 30 Jun 2014 23:59:00 -0400",
section_name: "Home, Garden & Pets Deals",
section_sort: "46",
hotness: 0,
categories: [
{
id: 198,
name: "Garden",
primary: true
}
],
stores: [
{
id: 958,
name: "Home Depot",
primary: true
}
],
price: "0.00",
price_text: "Free",
price_extra: "+ pickup after rebate",
billable": "1",
images: {
small: {
url: ""http://s3.dlnws.com/images/products/images/1414000/1414854-small",
width: "20",
height: "48"
},
medium: {
url: "http://s3.dlnws.com/images/products/images/1414000/1414854-medium",
width: "31",
height: "75"
},
large: {
url: ""http://s3.dlnws.com/images/products/images/1414000/1414854-large",
width: "52",
height: "125"
},
xlarge: {
url: ""http://s3.dlnws.com/images/products/images/1414000/1414854-xlarge",
width: "105",
height: "250"
}
},
mfg_part_no: "274250",
brand: "",
api_link: "https://api.dealnews.com/item/deal/1026582",
related_link: "https://api.dealnews.com/item/deal/1026582/related"
}
Fetching related deals and comments that have been posted to a deal can be retrieved by making calls to the appropriate specified resources.
GET /deals
GET /deals/choice
GET /deals/edition/<YYYY-MM-DD>
Equivalent to /deals/edition/ using today's date
GET /deals/today
GET /deals/search?...
Along with the inputs available to the base /deals call, /deals/search has the following additional inputs:
| Key | Type | Default | Description |
|---|---|---|---|
| expired | integer | 0 | If non-zero, deals that have passed their expire date will be included in the results. |
| exclusive | integer | 0 | If non-zero, only DealNews exclusive deals will be included in the results. |
| min_publication_date | date string | unset | If set, only deals published after the specified date will be returned. Format is YYYY-MM-DD. |
| max_publication_date | date string | unset | If set, only deals published before the specified date will be returned. Format is YYYY-MM-DD. |
| min_price | float | unset | If set, only deals with a price greater or equal to the value will be returned. |
| max_price | float | unset | If set, only deals with a price less or equal to the value will be returned. |
| allow_null_price | integer | 0 | If a minimum or maximum price is set, set this value to non-zero to allow for deals without a price to be retrieved. WARNING: this will be ignored if keywords are specified. |
| categories | comma separated integers | unset | If specified, only deals matching the provided category ids will be returned. |
| stores | comma separated integers | unset | If specified, only deals matching the provided store ids will be returned. |
| brands | comma separated integers | unset | If specified, only deals matching the provided brand ids will be returned. |
| keywords | string | unset | If specified only deals matching the given keywords will be returned. |
Retrieve a list of all the stores corresponding to retrieved deals. All query string parameters are applied to the /deals call and then the resulting list of matching stores is returned.
GET /deals/.../stores?...
Retrieve a list of all the categories corresponding to retrieved deals. All query string parameters are applied to the /deals call and then the resulting list of matching categories is returned.
GET /deals/.../categories?...
Retrieve a list of all the brands corresponding to retrieved deals. All query string parameters are applied to the /deals call and then the resulting list of matching brands is returned.
GET /deals/.../brands?...
The structure of the coupons resource is as follows:
/coupons
/search
The following inputs are valid for a /coupons call
| Key | Type | Default | Description |
|---|---|---|---|
| sort | string | first_publish_time | This value specifies how the returned content is sorted. The valid sort values are hotness, first_publish_time, and expiration. |
- The default number of coupons returned in a call is 30
- The maximum value of the limit parameter is 250
All coupons are formatted like so:
{
content_type: "COUPON",
id: 470553,
stores: [
{
id: 478,
name: "AllPosters.com",
logo: "http://images.dealnews.com/vendors/478-Small-Logo-120-X60-.png",
primary: true
}
],
categories: [
{
id: "200",
name: "Decor",
primary: true
}
],
store_id: 478,
store_name: "AllPosters.com",
short_store_name: "AllPosters.com",
code: "MOTHER25",
link: "...",
pub_date: "Thu, 10 Apr 2014 17:56:41 -0400",
expires: "Wed, 30 Apr 2014 23:59:00 -0400",
description_brief: "25% off no min coupon",
description: "25% off at AllPosters.com",
popularity: "0",
notes: "Exclusions apply.",
api_link: "https://api.dealnews.com/item/coupon/470553"
}
GET /coupons
GET /coupons/search?...
Along with the inputs available to the base /coupons call, /coupons/search has the following additional inputs:
| Key | Type | Default | Description |
|---|---|---|---|
| min_publication_date | date string | unset | If set, only deals published after the specified date will be returned. Format is YYYY-MM-DD. |
| max_publication_date | date string | unset | If set, only deals published before the specified date will be returned. Format is YYYY-MM-DD. |
| categories | comma separated integers | unset | If specified, only deals matching the provided category ids will be returned. |
| stores | comma separated integers | unset | If specified, only deals matching the provided store ids will be returned. |
Retrieve a list of all the stores corresponding to a set of retrieved coupons. All query string parameters are applied to the /coupons call and then the resulting list of matching stores is returned.
GET /coupons/.../stores?...
The structure of the features resource is as follows:
/features
Other than the defaults, the /features call has no additional query string parameters.
- The default number of features returned in a call is 30
- The maximum value of the limit parameter is 250
All features are formatted like so:
{
content_type: "FEATURE",
id: 1025115,
title: "53% of Walmart Shoppers Prefer Amazon to Walmart.com: What's the Deal?"
brief_title: "Most Walmart Shoppers Prefer Amazon's Site"
description_html: "...",
description_text: "...",
link: "...",
short_link: "...",
buy_now_link: "...",
pub_date: "Fri, 11 Apr 2014 08:00:01 -0400",
updated: "4 hr 24 min ago",
expires: "",
hotness: 0,
categories: [
{
id: 700,
name: "Consumer News",
primary: true
}
],
stores: [ ]
price: "",
price_text: "e-commerce",
price_extra: "",
images: {
small: {
url: "http://s3.dlnws.com/images/products/images/1414000/1414641-small",
width: "48",
height: "38"
},
medium: {
url: "http://s3.dlnws.com/images/products/images/1414000/1414641-medium",
width: "75",
height: "59"
},
large: {
url: "http://s3.dlnws.com/images/products/images/1414000/1414641-large",
width: "125",
height: "98"
},
xlarge: {
url: "http://s3.dlnws.com/images/products/images/1414000/1414641-xlarge",
width: "250",
height: "196"
}
},
brand: ""
api_link: "https://api.dealnews.com/item/feature/470553"
}
GET /features
Retrieve a list of all the brands corresponding to retrieved features. All query string parameters are applied to the /features call and then the resulting list of matching stores is returned.
GET /features/stores
Retrieve a list of all the categories corresponding to retrieved features. All query string parameters are applied to the /features call and then the resulting list of matching categories is returned.
GET /features/categories
Retrieve a list of all the brands corresponding to retrieved features. All query string parameters are applied to the /features call and then the resulting list of matching brands is returned.
GET /features/brands
The structure of the black friday resource is as follows:
/blackfriday
/<YYYY>
/search
The following inputs are valid for a /blackfriday call
| Key | Type | Default | Description |
|---|---|---|---|
| sort | string | datestamp | This value specifies how the returned content is sorted. The valid sort values are hotness, datestamp, and clicks. |
- The default number of black friday ads returned in a call is 30
- The maximum value of the limit parameter is 250
GET /blackfriday
GET /blackfriday/YYYY
GET /blackfriday/search?...
Along with the inputs available to the base /blackfriday call, /blackfriday/search has the following additional inputs:
| Key | Type | Default | Description |
|---|---|---|---|
| min_price | float | unset | If set, only deals with a price greater or equal to the value will be returned. |
| max_price | float | unset | If set, only deals with a price less or equal to the value will be returned. |
| editors_choice | integer | unset | This is a tri-state variable. If the parameter is not specified in the query string, Editor's Choice deals will be included in the results. If the value is 0, no Editor's Choice deals will be included in the results. If the value is 1, only Editor's Choice deals will be returned. |
| categories | comma separated integers | unset | If specified, only deals matching the provided category ids will be returned. |
| stores | comma separated integers | unset | If specified, only deals matching the provided store ids will be returned. |
| brands | comma separated integers | unset | If specified, only deals matching the provided brand ids will be returned. |
| keywords | string | unset | If specified only deals matching the given keywords will be returned. |
Retrieve a list of all the stores corresponding to retrieved black friday content. All query string parameters are applied to the /blackfriday call and then the resulting list of matching stores is returned.
GET /blackfriday/.../stores?...
A comprehensive list of stores can be retrieved by making the following API call:
/stores
Other than the defaults, the /stores call has no additional query string parameters.
- The default number of content items returned in this call is 30
- The maximum value of the limit parameter is 100
All stores are formatted like so:
{
store_id: 1422,
name: "1&1 Internet",
popularity: 182,
url: "...",
logo: "http://images.dealnews.com/vendors/1422-Small-Logo-120-X60-.png",
button: "http://images.dealnews.com/vendors/1-1-Internet-2-1255719221.png",
resources: [
{
url: "https://api.dealnews.com/stores/1422",
title: "Store data for 1&1 Internet",
description: "Store data for 1&1 Internet",
tag: "store_page"
}
]
}
All the content for a specific store can be retrieved by making the following API call:
/stores/<store id>
Note that this call will generally result in two datasets being returned. One with deals and another with coupons.
The following inputs are valid for a /stores/<store id> call
| Key | Type | Default | Description |
|---|---|---|---|
| promoted | integer | 0 | If a non-zero value is specified, then promoted content will be included in the list that is returned. |
A comprehensive list of categories can be retrieved by making the following API call:
/categories
Other than the defaults, the /categories call has no additional query string parameters.
- The default number of content items returned in this call is 30
- The maximum value of the limit parameter is 100
All categories are formatted like so:
{
category_id: 99,
name: "AMD Processors",
parent: 94,
children: [
389,
390,
391,
392,
393
],
resources: [
{
url: "https://api.dealnews.com/categories/99",
name: "AMD Processors",
title: "Category data for AMD Processors",
description: "Category data for AMD Processors",
tag: "category_page"
}
]
}
The list of top categories can be found at the following resource:
/categories/top
All the content for a specific category can be retrieved by making the following API call:
/categories/<catgory id>
The following inputs are valid for a /categories/<category id> call
| Key | Type | Default | Description |
|---|---|---|---|
| promoted | integer | 0 | If a non-zero value is specified, then promoted content will be included in the list that is returned. |
A comprehensive list of brands can be retrieved by making the following API call:
/brands
Other than the defaults, the /brands call has no additional query string parameters.
- The default number of content items returned in this call is 30
- The maximum value of the limit parameter is 100
All brands are formatted like so:
{
brand_id: 42659,
name: "'47 Brand",
resources: [
{
url: "https://api.dealnews.com/brands/42659",
title: "Brand data for '47 Brand",
description: "Brand data for '47 Brand",
tag: "brand_page"
}
]
}
All the content for a specific brand can be retrieved by making the following API call:
/brands/<brand id>
Other than the defaults, the /brands/<brand id> call has no additional query string parameters.