Deal Object

The Deal object is returned by the Browsing Deals request (in the dr array of its deals response object). Each entry combines basic product information with the current, previous and average prices/ranks across several date ranges, so you can see at a glance what changed and by how much.

Format#

{
// product information
    "asin": String,
    "parentAsin": String,
    "title": String,
    "rootCat": Long,
    "categories": Long array,
    "image": Integer array,

// price/rank information
    "current": Integer array,
    "currentSince": Integer array,
    "deltaLast": Integer array,
    "delta": two dimensional Integer array,
    "deltaPercent": two dimensional Integer array,
    "avg": two dimensional Integer array,

// deal information
    "lastUpdate": Integer,
    "creationDate": Integer,
    "lightningEnd": Integer,
    "warehouseCondition": Integer,
    "warehouseConditionComment": String
}

Fields#

Product information#

Price and rank information#

Deal information#

Lightning, Prime Exclusive and Warehouse Deals#

Keepa Time Minutes#

Time format used for all timestamps. To convert to an uncompressed Unix epoch time:

• For milliseconds: (keepaTime + 21564000) * 60000
• For seconds: (keepaTime + 21564000) * 60

const unixMs = (keepaTime + 21564000) * 60000;
const unixSeconds = (keepaTime + 21564000) * 60;
const date = new Date(unixMs);

Example#

Deal objects are retrieved via the Browsing Deals request. The query JSON can be sent as the POST payload or, URL-encoded, in the selection GET parameter — see the endpoint page for all query options and the token cost.

KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
DealRequest dealQuery = new DealRequest();
dealQuery.page = 0;
dealQuery.domainId = 1;               // amazon.com
dealQuery.priceTypes = new int[]{0};  // AMAZON price type
dealQuery.dateRange = 1;              // interval: last week
dealQuery.isRangeEnabled = true;
dealQuery.currentRange = new int[]{500, 40000};
dealQuery.deltaPercentRange = new int[]{20, 100};
dealQuery.sortType = 4;
api.sendRequest(Request.getDealsRequest(dealQuery))
    .done(result -> {
        for (Deal deal : result.deals.dr) {
            System.out.println(deal.asin + "  " + deal.title);
        }
    })
    .fail(failure -> System.out.println(failure));

<?php
use Keepa\KeepaAPI;
use Keepa\API\Request;
use Keepa\API\ResponseStatus;
use Keepa\objects\AmazonLocale;

use Keepa\API\DealRequest;
$api = new KeepaAPI("YOUR_API_KEY");
$dealQuery = new DealRequest();
$dealQuery->page = 0;
$dealQuery->domainId = 1;               // amazon.com
$dealQuery->priceTypes = [0];           // AMAZON price type
$dealQuery->dateRange = 1;              // interval: last week
$dealQuery->isRangeEnabled = true;
$dealQuery->currentRange = [500, 40000];
$dealQuery->deltaPercentRange = [20, 100];
$dealQuery->sortType = 4;
$response = $api->sendRequestWithRetry(Request::getDealsRequest($dealQuery));
if ($response->status == ResponseStatus::OK) {
    foreach ($response->deals->dr as $deal) {
        echo $deal->asin . "  " . $deal->title . PHP_EOL;
    }
}

import requests

query = {"page": 0, "domainId": 1, "priceTypes": [0], "dateRange": 1}
r = requests.post("https://api.keepa.com/deal",
                  params={"key": "YOUR_API_KEY"}, json=query)
data = r.json()

for deal in data["deals"]["dr"]:
    image_name = "".join(chr(c) for c in deal["image"])
    print(deal["asin"], deal["title"], deal["current"][0], image_name)

const query = { page: 0, domainId: 1, priceTypes: [0], dateRange: 1 };
const res = await fetch("https://api.keepa.com/deal?key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(query)
});
const data = await res.json();

for (const deal of data.deals.dr) {
  const imageName = String.fromCharCode.apply("", deal.image);
  console.log(deal.asin, deal.title, deal.current[0], imageName);
}

curl -s -X POST "https://api.keepa.com/deal?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":0,"domainId":1,"priceTypes":[0],"dateRange":1}'

Example Deal object#

{
  "asin": "B00M0QVG3W",
  "parentAsin": "B01D0MKH5V",
  "title": "Canon PowerShot SX400 Digital Camera with 30x Optical Zoom (Black)",
  "rootCat": 562066,
  "categories": [569604],
  "image": [54, 49, 107, 51, 76, 97, 121, 55, 74, 85, 76, 46, 106, 112, 103],
  "current": [12999, 12999, 9850, 1859],
  "currentSince": [7661010, 7661010, 7658200, 7661900],
  "deltaLast": [-3000, -3000, 0, 245],
  "delta": [
    [3000, 3000, 0, -217],
    [1800, 1651, -51, -139],
    [1600, 1524, -130, -44],
    [1313, 1201, -200, -69]
  ],
  "deltaPercent": [
    [19, 19, 0, -13],
    [12, 11, -1, -8],
    [11, 10, -1, -2],
    [9, 8, -2, -4]
  ],
  "avg": [
    [15999, 15999, 9850, 1642],
    [14799, 14650, 9799, 1720],
    [14599, 14523, 9720, 1815],
    [14312, 14200, 9650, 1790]
  ],
  "lastUpdate": 7661998,
  "creationDate": 7661010,
  "lightningEnd": 0,
  "warehouseCondition": 3,
  "warehouseConditionComment": "Item will come repackaged. Small cosmetic scratch on the bottom of the casing."
}

Example shortened for readability; illustrative values. The one-dimensional arrays (current, currentSince, deltaLast) are indexed by price type; only the first four entries are shown here (see the csv field of the product object for the full price type indexing — in a real response the arrays cover all price types). The two-dimensional arrays contain one row per date range (day, week, month, 90 days). Prices are integers in the locale’s smallest currency unit (here: US cents, e.g. 12999 = $129.99); timestamps are Keepa Time minutes (e.g. 7661010 → Unix ms (7661010 + 21564000) * 60000 = 1753500600000). The image array decodes to 61k3Lay7JUL.jpg, and warehouseCondition 3 means “Used - Very Good”.