# Graph Image API

Source: https://env.7xmtools.com/api-docs/graph-image.html

Retrieve a price history graph of a product as a ready-to-display PNG image. Choose which data series to draw, set the time range and image size, and customize every chart color.

GET · 1 token per image

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.

> **Note:** Graph images are cached for **90 minutes** on a per-user basis. Submitting the exact same request within this time frame will not consume any tokens.

> **Important:** Make sure you do **not** embed the images directly, as this will make your API key publicly accessible and open to misuse. Always put the Graph Image requests behind a proxy to secure your API key.

> **Note:** This API call returns PNG images as a response and does not provide your token status information. Any other API request returns your current token status in its response envelope (see [Response Format](https://env.7xmtools.com/api-docs/request-basics.html#response-format)).

## Endpoint

```
GET https://api.keepa.com/graphimage?key=<yourAccessKey>&domain=<domainId>&asin=<ASIN>
```

## Parameters

### Required parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `key` | required | Your private API key. |
| `domain` | required | Integer value for the Amazon locale you want to access. See the valid values below. |
| `asin` | required | The ASIN of the product. |

Valid values for `domain`:

| Domain ID | Locale |
| --- | --- |
| **1** | com |
| **2** | co.uk |
| **3** | de |
| **4** | fr |
| **5** | co.jp |
| **6** | ca |
| **8** | it |
| **9** | es |
| **10** | in |
| **11** | com.mx |
| **12** | com.br |

### 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:

| # | Graph | Shows | Selected with |
| --- | --- | --- | --- |
| 1 | Price history | Price trends and root category Sales Rank. | [`types`](https://env.7xmtools.com/api-docs/graph-image.html#param-types) |
| 2 | Category Sales Ranks & Monthly Sales | Sales ranks by category and monthly sales data. | [`subranks`, `monthlysold`](https://env.7xmtools.com/api-docs/graph-image.html#rank-graphs) |
| 3 | Offer Counts and Ratings | Number of offers, star rating and rating counts. | [`types`](https://env.7xmtools.com/api-docs/graph-image.html#param-types) |

Graphs 1 and 3 are made of [csv types](https://env.7xmtools.com/api-docs/product-object.html#csv-array) 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.

> **Important:** `types` and the sales rank parameters are **mutually exclusive**. A request naming both returns the bad-request image.

> **Default:** a request that selects no series at all draws the Amazon and New price series of graph 1. That defaulting does not apply once `types` or the sales rank parameters are used — those select the series completely.

### `types` — select by csv type index

Comma-separated [csv type indexes](https://env.7xmtools.com/api-docs/product-object.html#csv-array), 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:

| Graph | csv types |
| --- | --- |
| 1 — Price history | • `0` AMAZON<br>• `1` NEW<br>• `2` USED<br>• `3` SALES<br>• `4` LISTPRICE<br>• `5` COLLECTIBLE<br>• `6` REFURBISHED<br>• `7` NEW\_FBM\_SHIPPING<br>• `8` LIGHTNING\_DEAL<br>• `9` WAREHOUSE<br>• `10` NEW\_FBA<br>• `15` EXTRA\_INFO\_UPDATES<br>• `18` BUY\_BOX\_SHIPPING<br>• `19` USED\_NEW\_SHIPPING<br>• `20` USED\_VERY\_GOOD\_SHIPPING<br>• `21` USED\_GOOD\_SHIPPING<br>• `22` USED\_ACCEPTABLE\_SHIPPING<br>• `23` COLLECTIBLE\_NEW\_SHIPPING<br>• `24` COLLECTIBLE\_VERY\_GOOD\_SHIPPING<br>• `25` COLLECTIBLE\_GOOD\_SHIPPING<br>• `26` COLLECTIBLE\_ACCEPTABLE\_SHIPPING<br>• `27` REFURBISHED\_SHIPPING<br>• `28` EBAY\_NEW\_SHIPPING<br>• `29` EBAY\_USED\_SHIPPING<br>• `30` TRADE\_IN<br>• `32` BUY\_BOX\_USED\_SHIPPING<br>• `33` PRIME\_EXCL |
| 3 — Offer Counts and Ratings | • `11` COUNT\_NEW<br>• `12` COUNT\_USED<br>• `13` COUNT\_REFURBISHED<br>• `14` COUNT\_COLLECTIBLE<br>• `16` RATING<br>• `17` COUNT\_REVIEWS<br>• `34` COUNT\_NEW\_FBA<br>• `35` COUNT\_NEW\_FBM |

See the [csv History Array](https://env.7xmtools.com/api-docs/product-object.html#csv-array) for what each type contains.

> **Important:** A request naming both graphs — e.g. `&types=16,18` — is rejected. So is a malformed index, an unknown type, or a color that is not six hex digits. These are refused rather than silently dropped, because a dropped series is indistinguishable from missing data.

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

| Parameter | Required | Description | Valid values | Example |
| --- | --- | --- | --- | --- |
| `subranks` | optional | The **presence** of this parameter requests this graph. `0` draws the reference category only; `1` also draws the product’s other categories. | `0`, `1` | `&subranks=1` |
| `cRanks` | optional | Base color for the rank series. Additional categories are drawn in progressively darker shades derived from it, so one color covers however many categories a product has. Category selection is not exposed: which categories a product is ranked in is a property of the product. | hex color, e.g. `8fbc8f` | `&cRanks=8fbc8f` |
| `monthlysold` | optional | Draw the monthly sold series, on its own axis. Can be requested with or without ranks. | `1` | `&monthlysold=1` |
| `cMonthlysold` | optional | Color of the monthly sold series. | hex color, default `f6d500` | `&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

| Parameter | Required | Description | Valid values | Default | Example |
| --- | --- | --- | --- | --- | --- |
| `range` | optional | The range of the chart in days. | Suggested values: `1`, `2`, `7`, `31`, `90`, `365` | `90` | `&range=90` |
| `yzoom` | optional | Enable Close-up View (y-axis zoom). | `1` (zoom), `0` (no zoom) | `1` | `&yzoom=0` |
| `width` | optional | Width of the chart image in pixels. Values below the minimum are raised to it. | `300` to `1800` | `500` | `&width=500` |
| `height` | optional | Height of the chart image in pixels. Values below the minimum are raised to it. | `150` to `1800` | `200` | `&height=200` |
| `title` | optional | Include the product title. | `1` (show), `0` (hide) | `1` | `&title=0` |
| `legend` | optional | Include the chart legend. | `1` (show), `0` (hide) | `1` | `&legend=0` |
| `lw` | optional | Width of the drawn series lines. Applied proportionally to each series’ own weight, so their relative thicknesses are preserved. Applies to all three graph types. A value outside the valid range is **rejected**, not clamped. | `0.5` to `3.0` | `1.5` | `&lw=2` |

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

| Parameter | Required | Description | Example |
| --- | --- | --- | --- |
| `cBackground` | optional | Chart background color. | `&cBackground=ffffff` |
| `cFont` | optional | Font color. | `&cFont=444444` |

## 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](https://env.7xmtools.com/api-docs/request-basics.html#response-format).

The generated PNG contains a chart for the requested product:

- Which series are drawn is controlled by [series selection](https://env.7xmtools.com/api-docs/graph-image.html#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](https://env.7xmtools.com/api-docs/settings.html) 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:

```bash
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:

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

**Java**

```java
// 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**

```php
<?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));
```

**Python**

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

**Node.js**

```javascript
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()));
```

**cURL**

```bash
# 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
```

**HTML**

```html
<!--
  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">
```

> **Tip:** A minimal proxy only needs to forward the whitelisted graph parameters (e.g. `asin`, `range`) to `api.keepa.com/graphimage`, append your secret `key` server-side, and stream the PNG back. Combined with Keepa's 90-minute per-user cache, repeated views of the same chart cost no additional tokens.