Skip to content

DealNews Public API

Jump to bottom Edit New page
billspeir edited this page Apr 10, 2014 · 8 revisions

Public API Endpoint

The DealNews API is a RESTish style web service. See this article for a complete 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

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 (located at /deals), coupons (/coupons) and feature articles (/features). Second there are Ancillary resources that consists of stores, categories and brands. Below the top-level resources may be sub-resources allowing for related, but distinct results 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.

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

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,
    message: "Missing Authentication header."
}

or, in XML:

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

Common Inputs

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

Key Value
refcode Links will be tagged with the refcode provided.
limit An integer value that limits the number of returned items. 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 An integer which allows for pagination of returned content if the number of items matched exceeds the number of items returned (the limit).
sort A string value which allows sorting of the returned content. The valid sort values depends on the API resource being requested.
promoted If a non-zero value is specified, then promoted content will be included in any data that is returned.

Generalized Output Format

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.

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",
            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/brands",
            title: "Brand List",
            description: "Complete list of brands",
            tag: "brands"
        },
        {
            url: "https://api.dealnews.com/categories",
            title: "Category List",
            description: "Complete list of categories",
            tag: "categories"
        }
    ]
}

Content Resources - Deals, Coupons, Feature Articles

Deals

The structure of the deals resource is as follows:

/deals
    /today
    /edition/<YYYY-MM-DD>
    /choice
    /search

Furthermore, you can appended /stores, /categories or /brands to any of the above resources to retrieve the associated ancillary content related to the provided content. For example,

/deals/today/stores
/deals/edition/2012-07-01/categories
  • The default and maximum limit for returned deals is 100
  • The valid sort parameters are hotness, first_publish_time, latest_publish_time and price. The default value is first_publish_time.

If you are a partner, all deals are formatted like so:

    {
        content_type: "ARTICLE",
        id: 591410,
        title: "30 Shark EuroPro Space Saving Hangers w/ 4 Stain Guards for $5 + $5 s&h",
        brief_title: "30 Space Saving Hangers for $5",
        description_html: "...",
        description_text: "...",
        link: "...",
        buy_now_link: "...",
        pub_date: "Fri, 06 Jul 2012 05:15:03 -0400",
        expires: "Fri, 06 Jul 2012 23:59:00 -0400",
        section_name: "Home, Garden & Pets Deals",
        section_sort: "45",
        hotness: 0,
        categories: [
            {
                id: 637,
                name: "Cleaning & Laundry Supplies",
                primary: true
            }
        ],
        stores: [
            {
                id: 981,
                name: "JustDeals",
                primary: true
            }
        ],
        price: "5.00",
        price_text: "$5",
        price_extra: "",
        images: {
            small: {
                url: "http://s4.dlnws.com/images/products/images/1035000/1035886-small",
                width: "45",
                height: "48"
            },
            medium: {
                url: "http://s4.dlnws.com/images/products/images/1035000/1035886-medium",
                width: "71",
                height: "75"
            },
            large: {
                url: "http://s4.dlnws.com/images/products/images/1035000/1035886-large",
                width: "118",
                height: "125"
            },
            xlarge: {
                url: "http://s4.dlnws.com/images/products/images/1035000/1035886-xlarge",
                width: "235",
                height: "250"
            }
        },
        mfg_part_no: "",
        brand: "Shark"
    }

If you are a device, all deals are formatted like so:

{
    content_type: "ARTICLE",
    id: 1025580,
    title: "Designer's Collection Memory Foam Bath Mat for $6 + $4 s&h",
    brief_title: "Memory Foam Bath Mat for $6",
    short_link: "http://dn.ws/lzcc:iapp-dn-ios-1_9_1",
    buy_now_link: "http://dealnews.com/lw/artclick.html?2,1025580,7455630,iref=app-dn-ios-1_9_1,uid=396122",
    pub_date: "Thu, 10 Apr 2014 10:01:39 -0400",
    description_html: "...",
    description: "...",
    full_title_price_start: 47,
    full_title_price_len: 2,
    brief_title_price_start: 25,
    brief_title_price_len: 2,
    update_date: "Thu, 10 Apr 2014 10:01:39 -0400",
    updated: "3 min ago",
    expired: 0,
    hotness: 0,
    promoted: 0,
    store: "Tanga",
    store_id: 2216,
    category_id: 360,
    brand: "",
    price_text: "$6",
    price_image: "TAG",
    editors_choice: "0",
    comment_count: "0",
    images: {
        large: {
            url: "http://s3.dlnws.com/images/products/images/1414000/1414119-large",
            width: "125",
            height: "89"
        },
        xlarge: {
            url: "http://s3.dlnws.com/images/products/images/1414000/1414119-xlarge",
            width: "250",
            height: "179"
        }
    },
    resources: [
        {
            url: "https://api.dealnews.com/item/deal/1025580",
            title: "Deal Details",
            description: "Deal Details",
            tag: "api_link"
        },
        {
            url: "https://api.dealnews.com/item/deal/1025580/related",
            title: "Related Deals",
            description: "Related Deals",
            tag: "related_link"
        },
        {
            url: "https://api.dealnews.com/item/deal/1025580/comments",
            title: "Deal Comments",
            description: "Deal Comments",
            tag: "comments_link"
        }
    ]
}

Fetching Additional Data

Fetching related deals and comments that have been posted to a deal can be retrieved by making calls to the provided resources.

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

Key Value
expired 0 or 1, default: 0 - If non-zero, deals that have passed their expire date will be included in the results.
ended 0 or 1, default: 0 - If non-zero, deals that no longer show up on the dealnews.com front page will be included in the results.
editors_choice 0 or 1, default: 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.
exclusive 0 or 1, default: 0 - If non-zero, only DealNews exclusive deals will be included in the results.
min_publication_date YYYY-MM-DD - If set, only deals published after the specified date will be returned.
max_publication_date YYYY-MM-DD - If set, only deals published before the specified date will be returned.
min_price floating point value - If set, only deals with a price greater or equal to the value will be returned.
max_price floating point value - If set, only deals with a price less or equal to the value will be returned.
promoted 0 or 1, default 0 - If non-zero, promoted deals will also be included in the results.
categories comma separated integers - If specified, only deals matching the provided category ids will be returned.
stores comma separated integers - If specified, only deals matching the provided store ids will be returned.
brands comma separated integers - If specified, only deals matching the provided brand ids will be returned.
keywords text - 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.

GET /deals/.../stores

Categories

Retrieve a list of all the categories corresponding to retrieved deals.

GET /deals/.../categories

Brands

Retrieve a list of all the brands corresponding to retrieved deals.

GET /deals/.../brands

Coupons

The structure of the coupons resource is as follows:

/coupons
    /search

You can appended /stores to either of the above resources to retrieve the associated store content related to the provided content. For example,

/coupons/stores
  • The default and maximum limit for returned coupons is 100
  • The valid sort parameters are hotness, expiration and first_publish_time. The default value is first_publish_time.

If you are a partner, 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"
}

If you are a device, coupons are formatted like so:

{
    content_type: "COUPON",
    id: 470553,
    stores: [
        {
            id: 478,
            name: "AllPosters.com",
            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"
}

Current Coupons

GET /coupons

Search For Coupons

GET /coupons/search?...

Search Inputs

  • min_publication_date
  • max_publication_date
  • categories
  • stores

Coupons Sub Resources

Stores

Retrieve a list of all the stores corresponding to retrieved coupons.

GET /coupons/.../stores

Features

The structure of the features resource is as follows:

/features

You can appended /stores, /categories or /brands to any of the above resources to retrieve the associated ancillary content related to the provided content. For example,

/features/stores
  • The default and maximum limit for returned features is 100
  • Features does not support sort.

All features are formatted like so:

If you are a partner, all features are formatted like so:

{
    id: 591119,
    title: "Best Travel Deals: 1-Way Domestic Flights from $65, San Fran Hotels from $89",
    brief_title: "Top Travel: 1-Way Flights from $65",
    description_html: "...",
    description_text: "...",
    link: "...",
    buy_now_link: "...",
    pub_date: "Thu, 05 Jul 2012 11:45:02 -0400",
    expires: "",
    hotness: 0,
    categories: [
        {
            id: 634,
            name: "Best Travel Deals",
            primary: true
        }
    ],
    stores: [
        {
            id: 38659,
            name: "ShermansTravel",
            primary: true
        },
        {
            id: 5765,
            name: "Travelzoo",
            primary: false
        },
        {
            id: 38750,
            name: "Travelscream",
            primary: false
        },
        {
            id: 2813,
            name: "Frontier Airlines",
            primary: false
        },
        {
            id: 39522,
            name: "DealBase",
            primary: false
        }
    ],
    price: "65.00",
    price_text: "Best Travel Deals",
    price_extra: "",
    images: {
        small: {
            url: "http://s3.dlnws.com/images/products/images/987000/987786-small",
            width: "48",
            height: "48"
        },
        medium: {
            url: "http://s3.dlnws.com/images/products/images/987000/987786-medium",
            width: "75",
            height: "75"
        },
        large: {
            url: "http://s3.dlnws.com/images/products/images/987000/987786-large",
            width: "125",
            height: "125"
        },
        xlarge: {
            url: "http://s3.dlnws.com/images/products/images/987000/987786-xlarge",
            width: "250",
            height: "250"
        }
    },
    brand: ""
}

If you are a device, all features are formatted like so:

{
    content_type: "FEATURE",
    id: 1025658,
    title: "Go Find Your Fun: Save $142 on a Costa Rica Vacation, Flights to D.C. from $128",
    brief_title: "Find Your Fun: $142 off a Costa Rica Vacation",
    short_link: "...",
    buy_now_link: "...",
    pub_date: "Thu, 10 Apr 2014 13:07:35 -0400",
    description_html: "...",
    why_buy: "Forget relaxation, these travel deals bring the awesome",
    teaser: "...",
    update_date: "Thu, 10 Apr 2014 13:07:35 -0400",
    comment_count: "0",
    images: {
        large: {
            url: "http://s3.dlnws.com/images/products/images/1414000/1414263-large",
            width: "125",
            height: "125"
        }
    }

All Features

GET /features

Features Sub Resources

Stores

Retrieve a list of all the brands corresponding to retrieved features.

GET /features/stores

Categories

Retrieve a list of all the categories corresponding to retrieved features.

GET /features/categories

Brands

Retrieve a list of all the brands corresponding to retrieved features.

GET /features/brands

Black Friday<

The structure of the black friday resource is as follows:

/blackfriday
   /<YYYY>
   /search

You can appended /stores to any of the above resources to retrieve the associated store content related to the provided content. For example,

/blackfriday/stores
  • The default and maximum limit for returned blackfriday ads is 100
  • The valid sort parameters are hotness, datestamp. The default value is datestamp.

All Black Friday Ads

GET /blackfriday

Black Friday Ads for a Specific Year

GET /blackfriday/YYYY

Search For Black Friday Ads

GET /blackfriday/search?...

Search Inputs

  • categories
  • stores
  • brands

Black Friday Ads Sub Resources

Stores

Retrieve a list of all the brands corresponding to retrieved black friday content.

GET /blackfriday/.../stores

Ancillary Content - Categories, Brands, Stores

Stores

The structure of the stores resource is as follows:

/stores
        /<store id>

Categories

The structure of the categories resource is as follows:

/categories
        /<category id>

Top Categories

The list of top categories can be found at the following resource:

/categories/top

A typical response will look like the following. Each category returned has a link that can be used to fetch the deals for the category.

{
    status: "success",
    datasets: [{
        name: "categories",
        type: "array",
        categories_found: 13,
        categories_returned: 13,
        resources: [],
        categories: [{
            category_id: 238,
            name: "Automotive",
            parent: 0,
            children: [145, 357],
            resources: [{
                url: "https://api.dealnews.com/categories/238",
                name: "Automotive",
                title: "Category data for Automotive",
                description: "Category data for Automotive",
                tag: "category_page"
        }]
    },
    ...
    }]
}

Brands

The structure of the brands resource is as follows:

/brands
        /<brand id>
Add a custom footer
Add a custom sidebar
Clone this wiki locally