DealNews Public API

Public API Endpoint

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 and feature stories. 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.

Request Headers

HTTP Verbs

The only HTTP verb supported is GET. POST, PUT and DELETE are not supported.

Authorization

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

Return Data Formatting

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.

REFCODEs

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.

DealNews allows for customization of your referral code by appending a hyphen and an alphanumeric string to your REFCODE. 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 query string parameter 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, _, -, and 0-9.

Errors

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,
    path: "GET /",
    message: "Missing Authorization header."
}

or, in XML:

<dealnews>
    <status value="fatal_error" code="4" message="Missing Authorization header." />
</dealnews>

Common Inputs

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.

Common Outputs

General output fields

All successful API calls will have the following fields in the return data:

{
    status: "success",
    tracking_tag: "<img src=\"http://dealnews.com/lw/log_syndication.php?refcode=myrefcode\" width=\"1\" height\"=1\">"
    logo_image: "https://dealnews.a.ssl.fastly.net/images/dealnews/logos/poweredbycom.png"
    logo_link: "http://dealnews.com/?eref=myrefcode-logo"
    ...
}

or, in XML:

<dealnews>
    <status value="success"/>
    <tracking_tag>&lt;img src=&quot;http://dealnews.com/lw/log_syndication.php?refcode=myrefcode&quot; width=&quot;1&quot; height&quot;=1&quot;&gt;</tracking_tag>
    <logo_image>https://dealnews.a.ssl.fastly.net/images/dealnews/logos/poweredbycom.png</logo_image>
    <logo_link>http://dealnews.com/?eref=myrefcode-logo</logo_link>
    ...
</dealnews>

Related Resources

If there are other API endpoints that are related to the current API call (or dataset), they will be listed in a resources array.

{
    status: "success",
    ...
    resources: [
        {
            url: "https://api.dealnews.com/deals",
            name: "Deals",
            title: "Current Deals",
            description: "Recent deals that are still active",
            tag: "deals"
        },
        ...
    ]
}

or, in XML:

<dealnews>
    <status value="success"/>
    ...
    <resources>
        <resource url="https://api.dealnews.com/deals" name="Deals" title="Current Deals" description="Recent deals that are still active" tag="deals"/>
        ...
    </resources>
</dealnews>

The values in the name, title, and description fields should not be considered as constants and are subject to change. When programmatically searching through resources, applications should match the tag field as that is guaranteed not to change.

Resource arrays can also be contained in content containers.

Content Containers

Content items are returned within a dataset container. There may be multiple datasets returned in a single API call so dataset containers are contained in a datasets array.

For example, when a call to deals is made:

GET https://api.dealnews.com/deals?start=30

the result structure looks like the following for JSON:

{
    status: "success"
    ...
    datasets: [
        {
            name: "articles",
            type: "array",
            articles_found: 1043,
            articles_returned: 30,
            resources: [
                {
                    url: "https://api.dealnews.com/deals",
                    name: "Start",
                    title: "Start of results",
                    description: "Results from 1 to 30",
                    tag: "array_start"
                },
                ...
            ],
            articles: [
                {
                    content_type: ARTICLE,
                    id: 1638884,
                    ...
                },
                ...
            ]
        }
    ]
}

or, in XML:

<dealnews>
    <status value="success"/>
    ...
    <datasets>
        <dataset name="articles" type="array" articles_found="1516" articles_returned="30">
            <resources>
                <resource url="https://api.dealnews.com/deals" name="Start" title="Start of results" description="Results from 1 to 30" tag="array_start"/>
                ...
            </resources>
            <articles>
                <article>
                    <content_type>ARTICLE</content_type>
                    <id>1637645</id>
                    ...
                </article>
                ...
            </articles>
        </dataset>
    </datasets>
</dealnews>

Note the resources array contained within the dataset. Also note that the name of the dataset (in this case articles) matches the name of the array of content items.

Base Endpoint Call

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",
            name: "Deals",
            title: "Current Deals",
            description: "Recent deals that are still active",
            tag: "deals"
        },
        {
            url: "https://api.dealnews.com/features",
            name: "Features",
            title: "Feature Stories",
            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",
            name: "Black Friday",
            title: "Current Black Friday Ads",
            description: "Black Friday ads, coupons and deals",
            tag: "blackfriday"
        },
        {
            url: "https://api.dealnews.com/stores",
            name: "Stores",
            title: "All Stores",
            description: "Complete list of stores",
            tag: "stores"
        },
        {
            url: "https://api.dealnews.com/categories",
            name: "Categories",
            title: "All Categories",
            description: "Complete list of categories",
            tag: "categories"
        },
        {
            url: "https://api.dealnews.com/brands",
            name: "Brands",
            title: "All Brands",
            description: "Complete list of brands",
            tag: "brands"
        }
    ]
}

or, in XML:

<dealnews>
    <status value="success"/>
    ...
    <resources>
        <resource url="https://api.dealnews.com/deals" name="Deals" title="Current Deals" description="Recent deals that are still active" tag="deals"/>
        <resource url="https://api.dealnews.com/features" name="Features" title="Feature Stories" description="Where our readers go for more in-depth price trend information, buying advice, reviews, humor, and more" tag="features"/>
        <resource url="https://api.dealnews.com/blackfriday" name="Black Friday" title="Current Black Friday Ads" description="Black Friday ads, coupons and deals" tag="blackfriday"/>
        <resource url="https://api.dealnews.com/stores" name="Stores" title="All Stores" description="Complete list of stores" tag="stores"/>
        <resource url="https://api.dealnews.com/categories" name="Categories" title="All Categories" description="Complete list of categories" tag="categories"/>
        <resource url="https://api.dealnews.com/brands" name="Brands" title="All Brands" description="Complete list of brands" tag="brands"/>
        </resources>
</dealnews>

Content Resources - Deals, Feature Stories and Black Friday ads

Common Inputs

The following inputs can be provided on the query string for any content related API call:

Key	Type	Default	Description
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.

Deals

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 value of the limit parameter is 30
The maximum value of the limit parameter is 250

All deals are formatted like so:

{
    content_type: "ARTICLE",
    id: 1639028,
    title: "4Nt All-Inclusive Curacao Flight & Hotel Pkg from $1,633 for 2",
    brief_title" "4Nt All-Inclusive Curacao Vacation $1,633 for 2",
    offer_text: "4Nt All-Inclusive Curacao Flight & Hotel Pkg",
    description_html: "...",
    description_text: "...",
    link: "http://dealnews.com/4-Nt-All-Inclusive-Curacao-Flight-Hotel-Pkg-from-1-633-for-2/1639028.html?eref=myrefcode",
    short_link: "http://dn.ws/z4ok:emyrefcode",
    buy_now_link: "http://dealnews.com/lw/artclick.html?2,1639028,12663458,eref=myrefcode",
    pub_date: "Thu, 31 Mar 2016 08:10:34 -0400",
    updated: "3 hr 24 min ago",
    promoted: 0,
    expires: "Thu, 31 Mar 2016 23:59:00 -0400",
    section_name: "Travel & Entertainment Deals",
    section_sort: "45",
    hotness: 2,
    categories: [
        {
            id: 210,
            name: "Vacations",
            primary: true
        }
    ],
    stores: [
        {
            id: 38659,
            name: "ShermansTravel",
            primary: true
        }
    ],
    price: "1633.00",
    exact_price: "1632.82",
    price_text: "from $1,633 for 2",
    price_extra: "",
    rebates: [],
    coupons: [],
    coupon_details: [],
    billable: "1",
    images: {
        small: {
            url: "https://dealnews.a.ssl.fastly.net/images/products/images/1709000/1709134-small",
            width: 48,
            height: 29
        },
        medium: {
            url: "https://dealnews.a.ssl.fastly.net/images/products/images/1709000/1709134-medium",
            width: 75,
            height: 45
            },
        large: {
            url: "https://dealnews.a.ssl.fastly.net/images/products/images/1709000/1709134-large",
            width: 125,
            height: 75
        },
        xlarge: {
            url: "https://dealnews.a.ssl.fastly.net/images/products/images/1709000/1709134-xlarge",
            width: 250,
            height: 150
        }
    },
    mfg_part_no: "",
    brand: "",
    api_link: "https://api.dealnews.com/item/deal/1639028",
    related_link: "https://api.dealnews.com/item/deal/1639028/related"
}

or, in XML:

<article>
    <content_type>ARTICLE</content_type>
    <id>1639016</id>
    <title>Mountain Summit Gear Roll Top Table Station for $90 + free shipping</title>
    <brief_title>Mountain Summit Gear Roll Top Table Station $90</brief_title>
    <offer_text>Mountain Summit Gear Roll Top Table Station</offer_text>
    <description_html>...</description_html>
    <description_text>...</description_text>
    <link>http://dealnews.com/Mountain-Summit-Gear-Roll-Top-Table-Station-for-90-free-shipping/1639016.html?eref=myrefcode</link>
    <short_link>http://dn.ws/z4o8:ebillbert</short_link>
    <buy_now_link>http://dealnews.com/lw/artclick.html?2,1639016,12663554,eref=myrefcode</buy_now_link>
    <pub_date>Thu, 31 Mar 2016 08:24:58 -0400</pub_date>
    <updated>3 hr 17 min ago</updated>
    <promoted>0</promoted>
    <expires></expires>
    <section_name>Sports Deals</section_name>
    <section_sort>48</section_sort>
    <hotness>2</hotness>
    <categories>
        <category>
            <id>298</id>
            <name>Camping &amp; Outdoors</name>
            <primary>1</primary>
        </category>
    </categories>
    <stores>
        <store>
            <id>549</id>
            <name>REI</name>
            <primary>1</primary>
        </store>
    </stores>
    <price>90.00</price>
    <exact_price>89.73</exact_price>
    <price_text>$90</price_text>
    <price_extra>free shipping</price_extra>
    <rebates/>
    <coupons/>
    <coupon_details/>
    <billable>1</billable>
    <images>
        <image>
            <url>https://dealnews.a.ssl.fastly.net/images/products/images/1819000/1819151-small</url>
            <width>48</width>
            <height>38</height>
        </image>
        <image>
            <url>https://dealnews.a.ssl.fastly.net/images/products/images/1819000/1819151-medium</url>
            <width>75</width>
            <height>59</height>
        </image>
        <image>
            <url>https://dealnews.a.ssl.fastly.net/images/products/images/1819000/1819151-large</url>
            <width>125</width>
            <height>98</height>
        </image>
        <image>
            <url>https://dealnews.a.ssl.fastly.net/images/products/images/1819000/1819151-xlarge</url>
            <width>250</width>
            <height>196</height>
        </image>
    </images>
    <mfg_part_no>876246</mfg_part_no>
    <brand>Mountain Summit Gear</brand>
    <api_link>https://api.dealnews.com/item/deal/1639016</api_link>
    <related_link>https://api.dealnews.com/item/deal/1639016/related</related_link>
</article>

Fetching Additional Data

Fetching deals that are related to a deal can be retrieved by making calls to the specified related_link resource.

Current Deals

GET /deals

Current Editor's Choice Deals

GET /deals/choice

Deals for a specific day

GET /deals/edition/<YYYY-MM-DD>

Today's Deals

Equivalent to /deals/edition/<YYYY-MM-DD> using today's date

GET /deals/today

Search For Deals

GET /deals/search?...

Search Inputs

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.
ended	integer	0	If non-zero, return deals that have ended.
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.

Deals Sub Resources

Stores

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?...

Categories

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?...

Brands

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?...

Feature Stories

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 value of the limit parameter is 30
The maximum value of the limit parameter is 250

All features are formatted like so:

{
    content_type: "FEATURE",
    id: 1638407,
    title: "Best Kitchen Deals: 3-Piece Nonstick Skillet Set for $10",
    brief_title: "Best Kitchen Deals: 3 Nonstick Skillets for $10",
    description_html: "...",
    description_text: "...",
    link: "http://dealnews.com/features/best-kitchen-deals/?eref=myrefcode",
    short_link: "http://dn.ws/z47b:emyrefcode",
    buy_now_link: "http://dealnews.com/lw/artclick.html?2,1638407,12662663,eref=myrefcode",
    pub_date: "Thu, 31 Mar 2016 05:00:01 -0400",
    updated: "7 hr 23 min ago",
    expires: "Thu, 07 Apr 2016 23:59:00 -0400",
    hotness: 4,
    categories: [
        {
            id: 697,
            name: "Roundups",
            primary: true
        }
    ],
    stores: [
        {
            id: 288,
            name: "Macy's",
            primary: true
        },
        {
            id: 39848,
            name: "GearXS",
            primary: false
        },
        {
            id: 50,
            name: "eBay",
            primary: false
        }
    ],
    price: "",
    price_text: "",
    price_extra: "",
    images: {
        small: {
            url: "https://dealnews.a.ssl.fastly.net/images/products/images/1818000/1818800-small",
            width: 48,
            height: 48
        },
        medium: {
            url: "https://dealnews.a.ssl.fastly.net/images/products/images/1818000/1818800-medium",
            width: 75,
            height: 75
        },
        large: {
            url: "https://dealnews.a.ssl.fastly.net/images/products/images/1818000/1818800-large",
            width: 125,
            height: 124
        },
        xlarge: {
            url: "https://dealnews.a.ssl.fastly.net/images/products/images/1818000/1818800-xlarge",
            width: 250,
            height: 248
        }
    },
    brand: "Farberware",
    api_link: "https://api.dealnews.com/item/feature/1638407"
}

or, in XML:

<feature>
    <content_type>FEATURE</content_type>
    <id>1638407</id>
    <title>Best Kitchen Deals: 3-Piece Nonstick Skillet Set for $10</title>
    <brief_title>Best Kitchen Deals: 3 Nonstick Skillets for $10</brief_title>
    <description_html>...</description_html>
    <description_text>...</description_text>
    <link>http://dealnews.com/features/best-kitchen-deals/?eref=myrefcode</link>
    <short_link>http://dn.ws/z47b:emyrefcode</short_link>
    <buy_now_link>http://dealnews.com/lw/artclick.html?2,1638407,12662663,eref=myrefcode</buy_now_link>
    <pub_date>Thu, 31 Mar 2016 05:00:01 -0400</pub_date>
    <updated>8 hr 5 min ago</updated>
    <expires>Thu, 07 Apr 2016 23:59:00 -0400</expires>
    <hotness>4</hotness>
    <categories>
        <category>
            <id>697</id>
            <name>Roundups</name>
            <primary>1</primary>
        </category>
    </categories>
    <stores>
        <store>
            <id>288</id>
            <name>Macy's</name>
            <primary>1</primary>
        </store>
        <store>
            <id>39848</id>
            <name>GearXS</name>
            <primary></primary>
        </store>
        <store>
            <id>50</id>
            <name>eBay</name>
            <primary></primary>
        </store>
    </stores>
    <price></price>
    <price_text></price_text>
    <price_extra></price_extra>
    <images>
        <image>
            <url>https://dealnews.a.ssl.fastly.net/images/products/images/1818000/1818800-small</url>
            <width>48</width>
            <height>48</height>
        </image>
        <image>
            <url>https://dealnews.a.ssl.fastly.net/images/products/images/1818000/1818800-medium</url>
            <width>75</width>
            <height>75</height>
        </image>
        <image>
            <url>https://dealnews.a.ssl.fastly.net/images/products/images/1818000/1818800-large</url>
            <width>125</width>
            <height>124</height>
        </image>
        <image>
            <url>https://dealnews.a.ssl.fastly.net/images/products/images/1818000/1818800-xlarge</url>
            <width>250</width>
            <height>248</height>
        </image>
    </images>
    <brand>Farberware</brand>
    <api_link>https://api.dealnews.com/item/feature/1638407</api_link>
</feature>

All Features

GET /features

Features Sub Resources

Stores

Retrieve a list of all the stores 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

Categories

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

Brands

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

Black Friday

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`.

The default value of the limit parameter is 30
The maximum value of the limit parameter is 250

All Black Friday Ads are formatted like so:

{
    content_type: "BFAD",
    id: 6134650,
    description: "ThinkServer T Series Server Tower Sale!",
    tag: "NONE",
    price: "",
    part: "",
    image: "https://dealnews.a.ssl.fastly.net/images/cache/images/large/bu-aHR0cCUzQSUyRiUy/RnMxLmRsbndzLmNv/bSUyRmZpbGVzJTJG/aW1hZ2VzJTJGNTA2/NDQlMkYyMi5wbmc=",
    confirmed: 1,
    rebate: 0,
    quantity: 1,
    tags: "Limited Qty, Online Only, Confirmed",
    sort: 1448552129,
    url: "http://dealnews.com/lw/click.html?20,2,6134650,eref=myrefcode",
    categories: [
        {
            id: "39",
            name: "Computers",
            primary: true
        }
    ],
    stores: [
        {
            id: 1662,
            name: "Lenovo",
            primary: true
        }
    ],
    api_link: "https://api.dealnews.com/item/blackfriday/6134650",
    related_link: "https://api.dealnews.com/item/blackfriday/6134650/related"
}

or, in XML:

<bfad>
    <content_type>BFAD</content_type>
    <id>6134650</id>
    <description>ThinkServer T Series Server Tower Sale!</description>
    <tag>NONE</tag>
    <price></price>
    <part></part>
    <image>https://dealnews.a.ssl.fastly.net/images/cache/images/large/bu-aHR0cCUzQSUyRiUy/RnMxLmRsbndzLmNv/bSUyRmZpbGVzJTJG/aW1hZ2VzJTJGNTA2/NDQlMkYyMi5wbmc=</image>
    <confirmed>1</confirmed>
    <rebate>0</rebate>
    <quantity>1</quantity>
    <tags>Limited Qty, Online Only, Confirmed</tags>
    <sort>1448552129</sort>
    <url>http://dealnews.com/lw/click.html?20,2,6134650,eref=myrefcode</url>
    <categories>
        <category>
            <id>39</id>
            <name>Computers</name>
            <primary>1</primary>
        </category>
    </categories>
    <stores>
        <store>
            <id>1662</id>
            <name>Lenovo</name>
            <primary>1</primary>
        </store>
    </stores>
    <api_link>https://api.dealnews.com/item/blackfriday/6134650</api_link>
    <related_link>https://api.dealnews.com/item/blackfriday/6134650/related</related_link>
</bfad>

All Black Friday Ads

GET /blackfriday

This is equivalent to calling GET /blackfriday/YYYY where YYYY will be the current year if there are ads published for the year or the previous year if there are not yet ads published for the current year.

Black Friday Ads for a Specific Year.

GET /blackfriday/YYYY

Search For Black Friday Ads

GET /blackfriday/search?...

Search Inputs

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.
keywords	string	unset	If specified only deals matching the given keywords will be returned.

Black Friday Ads Sub Resources

Stores

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?...

Categories

Retrieve a list of all the categories 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/.../categories?...

Ancillary Data - Categories, Brands, Stores

Stores

List of 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 value of the limit parameter is 30
The maximum value of the limit parameter is 100

All stores are formatted like so:

{
    store_id: 5898,
    name: "1-800-Baskets",
    popularity: 0,
    url: "http://dealnews.com/lw/outclick.html?2,5898,iref=myrefcode",
    logo: "https://dealnews.a.ssl.fastly.net/images/vendors/-1-1337188556.gif",
    button: "https://dealnews.a.ssl.fastly.net/images/vendors/-2-1337188565.gif",
    featured: "0",
    resources: [
        {
            url: "https://api.dealnews.com/stores/5898",
            name: "1-800-Baskets",
            title: "Store data for 1-800-Baskets",
            description: "Store data for 1-800-Baskets",
            tag: "store_page"
        }
    ]
}

or, in XML:

<store>
    <store_id>5898</store_id>
    <name>1-800-Baskets</name>
    <popularity>0</popularity>
    <url>http://dealnews.com/lw/outclick.html?2,5898,iref=myrefcode</url>
    <logo>https://dealnews.a.ssl.fastly.net/images/vendors/-1-1337188556.gif</logo>
    <button>https://dealnews.a.ssl.fastly.net/images/vendors/-2-1337188565.gif</button>
    <featured>0</featured>
    <resources>
        <resource url="https://api.dealnews.com/stores/5898" name="1-800-Baskets" title="Store data for 1-800-Baskets" description="Store data for 1-800-Baskets" tag="store_page"/>
    </resources>
</store>

Content for a specific store

All the content for a specific store can be retrieved by making the following API call:

/stores/<store id>

Note that this call will 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.

Categories

List of Categories

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 value of the limit parameter is 30
The maximum value of the limit parameter is 100

All categories are formatted like so:

{
    category_id: 275,
    name: "Accessories",
    parent: 202,
    children: [
        436,
        454,
        481
    ],
    resources: [
        {
            url: "https://api.dealnews.com/categories/275",
            name: "Accessories",
            title: "Category data for Accessories",
            description: "Category data for Accessories",
            tag: "category_page"
        }
    ]
}

or, in XML:

<category>
    <category_id>275</category_id>
    <name>Accessories</name>
    <parent>202</parent>
    <children>
        <child>436</child>
        <child>454</child>
        <child>481</child>
    </children>
    <resources>
        <resource url="https://api.dealnews.com/categories/275" name="Accessories" title="Category data for Accessories" description="Category data for Accessories" tag="category_page"/>
    </resources>
</category>

Content for a specific category

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.

Brands

List of Brands

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 value of the limit parameter 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",
            name: "'47 Brand",
            title: "Brand data for '47 Brand",
            description: "Brand data for '47 Brand",
            tag: "brand_page"
        }
    ]

}

or, in XML:

<brand>
    <brand_id>42659</brand_id>
    <name>'47 Brand</name>
    <resources>
        <resource url="https://api.dealnews.com/brands/42659" name="'47 Brand" title="Brand data for '47 Brand" description="Brand data for '47 Brand" tag="brand_page"/>
    </resources>
</brand>

Content for a specific brand

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.

DealNews Public API

Public API Endpoint

Request Headers

HTTP Verbs

Authorization

Return Data Formatting

REFCODEs

Errors

Common Inputs

Common Outputs

General output fields

Related Resources

Content Containers

Base Endpoint Call

Content Resources - Deals, Feature Stories and Black Friday ads

Common Inputs

Deals

Fetching Additional Data

Current Deals

Current Editor's Choice Deals

Deals for a specific day

Today's Deals

Search For Deals

Search Inputs

Deals Sub Resources

Stores

Categories

Brands

Feature Stories

All Features

Features Sub Resources

Stores

Categories

Brands

Black Friday

All Black Friday Ads

Black Friday Ads for a Specific Year.

Search For Black Friday Ads

Search Inputs

Black Friday Ads Sub Resources

Stores

Categories

Ancillary Data - Categories, Brands, Stores

Stores

List of Stores

Content for a specific store

Categories

List of Categories

Content for a specific category

Brands

List of Brands

Content for a specific brand

Clone this wiki locally