> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rankraft.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Compare competitors over time

> A multi-line chart of Visibility Score, or any visibility metric, for you and a chosen set of competitors.

The "you vs. competitors" chart is one call: `group_by: ["date"]` with a list of brands. Each row is one brand on one day; pivot the rows into one series per brand.

> [!WARNING]
>
> Don't average these daily rows to get each brand's period score. Make one call without `date` instead: that is the [leaderboard](/cookbook/competitor-leaderboard).

## How this example works

1. **`group_by: ["date"]`** gives one row per brand per day.
2. **`brands`** as a list limits the rows to the brands you name (your own and confirmed competitors). Use `"all"` for everyone.
3. **Fetch every page.** Brands × days easily passes 100 rows.
4. **Pivot** into one series per brand, keyed by date, ready for a chart.

```js JavaScript theme={"system"}
import { RankRaft } from "rankraft-js";

const rr = new RankRaft();
const BRANDS = ["Misali Foods", "Shan Foods", "National Foods"];

const rows = await rr.reports
  .visibility({
    site_id: process.env.RANKRAFT_SITE_ID,
    start_date: "2026-09-01",
    end_date: "2026-09-30",
    group_by: ["date"],
    brands: BRANDS,
    metrics: ["visibility_score", "mention_rate"],
    limit: 100,
  })
  .all();

// { "Shan Foods": { "2026-09-01": 52, ... }, ... }
const series = {};
for (const r of rows) (series[r.brand.name] ??= {})[r.date] = r.visibility_score;

const missing = BRANDS.filter((b) => !Object.keys(series).some((n) => n.toLowerCase() === b.toLowerCase()));
if (missing.length) console.warn("Not your brand or a confirmed competitor:", missing);

const dates = [...new Set(rows.map((r) => r.date))].sort();
const names = Object.keys(series);
console.log(["date", ...names].join(","));
for (const d of dates) console.log([d, ...names.map((n) => series[n][d] ?? "")].join(","));
```

```python Python theme={"system"}
import os
from rankraft import RankRaft

BRANDS = ["Misali Foods", "Shan Foods", "National Foods"]

with RankRaft() as rr:
    df = rr.reports.visibility(
        site_id=os.environ["RANKRAFT_SITE_ID"],
        start_date="2026-09-01",
        end_date="2026-09-30",
        group_by=["date"],
        brands=BRANDS,
        metrics=["visibility_score", "mention_rate"],
        limit=100,
    ).to_pandas(all_pages=True)

# brand arrives as a {name, owned} object; take the name.
df["brand_name"] = df["brand"].map(lambda b: b["name"])
wide = df.pivot(index="date", columns="brand_name", values="visibility_score")
print(wide)

missing = {b.lower() for b in BRANDS} - {n.lower() for n in wide.columns}
if missing:
    print("Not your brand or a confirmed competitor:", missing)

# wide.plot() draws the chart in a notebook.
```

```bash curl theme={"system"}
curl https://api.rankraft.ai/v1/reports/visibility \
  -H "X-API-Key: $RANKRAFT_API_KEY" -H "Content-Type: application/json" \
  -d '{"site_id":"'$RANKRAFT_SITE_ID'","start_date":"2026-09-01","end_date":"2026-09-30",
       "group_by":["date"],"brands":["Misali Foods","Shan Foods","National Foods"],
       "metrics":["visibility_score","mention_rate"],"limit":100}'
```

## Notes

* Every brand on a day is scored against the **same answers**, so the lines are directly comparable.
* A competitor's `citation_rate` counts answers linking to the domains on its competitor entry. Add its domains in the dashboard if that line is flat at zero.
* Up to 20 brand names per call. Add `"platform"` to `group_by` for one chart per engine.
* `share_of_voice` makes a good stacked chart: each brand's share of all brand mentions that day.

## Common follow-ups

> **[Competitor leaderboard](/cookbook/competitor-leaderboard)**
>
> The same brands as one ranked table for the period.

> **[Visibility over time](/cookbook/visibility-over-time)**
>
> Weekly and monthly points.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.