Graph Image API

The Graph Image API renders the price history of a product as a static chart image in PNG format. The image is generated server-side from the requested data series, time range, size and colors, so it can be displayed anywhere an image can be shown. The Response section below describes what the generated PNG contains.

Endpoint#

Parameters#

Required parameters#

Valid values for domain:

Selecting series#

Keepa offers three graph types. Each one has its own axes and value space, so a single image can only ever contain series from one of them:

Graphs 1 and 3 are made of csv types and are selected with the types parameter. Graph 2 is not built from csv types — it is drawn from the product’s per-category rank histories and monthly sold — so it has its own parameters.

types — select by csv type index#

Comma-separated csv type indexes, each optionally followed by : and a six-digit hex color. A leading # is accepted (URL-encode it as %23) but is not required. Omitting the color uses the type’s default.

&types=16,17,11
&types=11:8888dd,12:444444,34:ff5722

All requested types must belong to the same graph. Every drawable type, by index:

See the csv History Array for what each type contains.

Category Sales Ranks & Monthly Sales#

Drawn from the product’s per-category rank histories and monthly sold — not from csv types, which is why it has its own parameters.

&subranks=0&monthlysold=1
&subranks=1&cRanks=8fbc8f&monthlysold=1&cMonthlysold=f6d500

Each category is scaled on its own axis. A product ranked #400 in a sub-category and #180,000 overall would otherwise draw the sub-rank as a flat line; independent scaling is what makes the shapes comparable.

Display parameters#

Color parameters#

The following parameters allow you to customize the colors of various chart elements. All color parameters are hexadecimal color codes (e.g., ff0000). These parameters are optional.

These apply to every request. Per-series colors are set through the parameter that selects the series: types=<index>:<color> for graphs 1 and 3, or cRanks / cMonthlysold for graph 2.

Token Cost#

1 token per image.

Because graph images are cached for 90 minutes on a per-user basis, repeating the exact same request (with identical parameters) within that time frame does not consume any tokens.

Response#

The response is a binary PNG image (not JSON). It does not include token-bucket status fields such as tokensLeft; those are returned by any other API request in its response envelope.

The generated PNG contains a chart for the requested product:

• Which series are drawn is controlled by series selection — types for graph 1 (Price history) and graph 3 (Offer Counts and Ratings), or subranks / monthlysold for graph 2 (Category Sales Ranks & Monthly Sales). A request that selects nothing draws the Amazon and New price series.
• The chart covers the time range set via range in days (default 90).
• The product title and the legend are included unless disabled with title=0 and legend=0, and the Close-up View y-axis zoom is enabled by default (yzoom=1).
• Background and font color can be customized via cBackground and cFont; per-series colors are set through the selecting parameter.
• Image dimensions follow width (300–1800 px, default 500) and height (150–1800 px, default 200), and the series line width follows lw (0.5–3.0, default 1.5).

Try it#

Build a request from every supported parameter, see the URL update as you go, and render the chart against the live API. Your stored API key is used for the request and is never shown in the URL below.

Examples#

Basic request#

Draws the default series (Amazon and New prices) for the last 90 days as a 500×200 px PNG:

https://api.keepa.com/graphimage?key=YOUR_API_KEY&domain=1&asin=B0F3GWXLTS

Customized request#

Selects the Amazon, New, Sales Rank and Buy Box series of graph 1 with types, widens the range to one year, enlarges the image, and overrides the Amazon series and background colors:

https://api.keepa.com/graphimage?key=YOUR_API_KEY&domain=1&asin=B0F3GWXLTS&types=0:FFA500,1,3,18&range=365&width=800&height=300&cBackground=ffffff

// The official SDKs have no dedicated /graphimage helper —
// request the PNG directly:
String url = "https://api.keepa.com/graphimage?key=YOUR_API_KEY"
        + "&domain=1&asin=B0F3GWXLTS&types=0:FFA500,1,3,18&range=365"
        + "&width=800&height=300&cBackground=ffffff";
try (InputStream in = new URL(url).openStream()) {
    Files.copy(in, Paths.get("graph.png"), StandardCopyOption.REPLACE_EXISTING);
}

<?php
// The official SDKs have no dedicated /graphimage helper —
// request the PNG directly:
$url = "https://api.keepa.com/graphimage?key=YOUR_API_KEY"
     . "&domain=1&asin=B0F3GWXLTS&types=0:FFA500,1,3,18&range=365"
     . "&width=800&height=300&cBackground=ffffff";
file_put_contents("graph.png", file_get_contents($url));

import requests

params = {
    "key": "YOUR_API_KEY",
    "domain": 1,
    "asin": "B0F3GWXLTS",
    "types": "0:FFA500,1,3,18",
    "range": 365,
    "width": 800,
    "height": 300,
    "cBackground": "ffffff",
}
r = requests.get("https://api.keepa.com/graphimage", params=params)
r.raise_for_status()

with open("graph.png", "wb") as f:
    f.write(r.content)  # binary PNG data

import { writeFile } from "node:fs/promises";

const url = "https://api.keepa.com/graphimage?key=YOUR_API_KEY&domain=1&asin=B0F3GWXLTS&types=0:FFA500,1,3,18&range=365&width=800&height=300&cBackground=ffffff";
const res = await fetch(url);
await writeFile("graph.png", Buffer.from(await res.arrayBuffer()));

# Save the generated chart to graph.png
curl -s "https://api.keepa.com/graphimage?key=YOUR_API_KEY&domain=1&asin=B0F3GWXLTS&types=0:FFA500,1,3,18&range=365&width=800&height=300&cBackground=ffffff" -o graph.png

<!--
  Serve the image through YOUR OWN proxy endpoint.
  Never reference api.keepa.com directly in public HTML:
  that would expose your API key to anyone viewing the page source.
-->
<img src="/keepa-proxy/graph?asin=B0F3GWXLTS&range=365"
     width="800" height="300"
     alt="Keepa price history graph">