Your brand, domains and competitors

Most “us vs. them” recipes need three things: your brand’s name as the reports spell it, the domains that count as your own site, and the competitors you are ranked against. The reports already apply all three — every visibility row says brand.owned, every citation row says owner — so you rarely need to match names or domains yourself. When you do, take them from the API rather than typing them in.

How this example works

Site — domain is your main domain.
Competitors — every competitor with its domains and a confirmed flag. Only confirmed ones are ranked and counted in share of voice.
Brand name — the brands: "owned" visibility row carries brand.name exactly as the reports use it.
Every own domain the engines cite — the citations report with owner = own returns your main domain plus any other domain on your brand profile that has been cited.

Cache the result. All of it changes only when someone edits the brand profile or the competitor list.

import { RankRaft, f } from "rankraft-js";

const rr = new RankRaft();
const site_id = process.env.RANKRAFT_SITE_ID;
const range = { site_id, start_date: "2026-09-01", end_date: "2026-09-30" };

const [site, competitors, owned, ownCited] = await Promise.all([
  rr.sites.get({ site_id }),
  rr.sites.competitors({ site_id }),
  rr.reports.visibility({ ...range, brands: "owned", metrics: ["answers"] }),
  rr.reports.citations({ ...range, entity: "domain", filter: f.is("owner", "own") }).all(),
]);

console.log("Brand:", owned.data[0]?.brand.name ?? "(no answers in range)");
console.log("Main domain:", site.domain);
console.log("Own domains cited:", ownCited.map((r) => r.domain));

console.log("\nCompetitors (ranked):");
for (const c of competitors.filter((c) => c.confirmed)) console.log(" ", c.name, c.domains.join(", "));
console.log("Found in answers, not yet confirmed:");
for (const c of competitors.filter((c) => !c.confirmed)) console.log(" ", c.name);

from rankraft import RankRaft, F
import os

site_id = os.environ["RANKRAFT_SITE_ID"]
range_ = dict(site_id=site_id, start_date="2026-09-01", end_date="2026-09-30")

with RankRaft() as rr:
    site = rr.sites.get(site_id=site_id)
    competitors = rr.sites.competitors(site_id=site_id)
    owned = rr.reports.visibility(**range_, brands="owned", metrics=["answers"])
    own_cited = rr.reports.citations(**range_, entity="domain", filter=F("owner").is_("own")).all()

print("Brand:", owned.data[0]["brand"]["name"] if owned.data else "(no answers in range)")
print("Main domain:", site["domain"])
print("Own domains cited:", [r["domain"] for r in own_cited])

print("\nCompetitors (ranked):")
for c in competitors:
    if c["confirmed"]:
        print(" ", c["name"], ", ".join(c["domains"]))
print("Found in answers, not yet confirmed:")
for c in competitors:
    if not c["confirmed"]:
        print(" ", c["name"])

curl https://api.rankraft.ai/v1/sites/$RANKRAFT_SITE_ID/competitors \
  -H "X-API-Key: $RANKRAFT_API_KEY"

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","brands":"owned","metrics":["answers"]}'

How ownership is decided

Question	Rule
Is an answer a mention of you?	It names your brand or one of its aliases. Aliases are set on the brand profile in the dashboard.
Is a citation your own site?	Its domain is your main domain or another domain on your brand profile. Subdomains count.
Is a citation a competitor’s?	Its domain, or a parent of it, is on any competitor’s list, confirmed or not.
Does a competitor appear in leaderboards?	Only when confirmed.

Competitors and the brand profile are edited in the dashboard, not over the API. Reports apply the current lists to past answers too; see Why past numbers change.

Get started

Metrics

Visibility

Citations

More recipes

How this example works

How ownership is decided

​How this example works

​How ownership is decided

How this example works

How ownership is decided