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

# Brand Visibility

> Ask Perplexity a question and get an AEO/GEO analysis of how your brand appears in the answer: mentions, position, share of voice against competitors, and whether your domain was cited.

Ask **the real `perplexity.ai`** a buyer-intent question and get back both the
answer **and** how your brand fares in it: whether it was mentioned, how early,
how often, how it compares to named competitors, and whether your domain was
cited as a source.

Accepts `GET` (query params) or `POST` (JSON body).

**Credits:** 25

> [!WARNING]
>
> A call can take up to about 75 s while exits are tried, so set your client
> timeout to at least 90 s. Every call renders a fresh answer: nothing is
> cached, so the same prompt sent again gets a new answer and is billed again.

## Authorization

**X-API-Key** `string` *required*

Your ScrapeBadger API key.

## Query Parameters

**prompt** `string` *required*

The question to ask, typically a buyer-intent prompt like
`best web scraping API for e-commerce`. Maximum 4,096 characters.

**brand** `string` *required*

The brand name to look for in the answer, e.g. `ScrapeBadger`.

**domain** `string`

Your domain, e.g. `scrapebadger.com`. Used for `cited`, `cited_urls` and
`citation_rank`.

**aliases** `string`

Alternate spellings that also count as a mention of `brand`.
**Comma-separated on `GET`; a `string[]` on `POST`.**

**competitors** `string`

Competitor names to measure against, e.g. `Bright Data,Oxylabs,Zyte`.
**Comma-separated on `GET`; a `string[]` on `POST`.**

**country** `string`

ISO-3166 alpha-2 market, e.g. `US`, `DE`, `JP`. Sets the ask's language and
timezone (e.g. `DE`: `de-DE`, `Europe/Berlin`). Omit it and the market whose
exits answer best right now is used.

The egress is **best-effort**: when that market has no exit left, another one
carries the ask and the response `country` says which. Set `strict_country`
to forbid that.

**strict\_country** `boolean` (default: false)

Answer only from an exit in `country`, never another one. When no exit there
answers in time the call fails with **`503`** and
`detail.code = "country_unavailable"`. It is **not billed** (only `2xx`
responses are). Requires `country` — `400` otherwise. A JSON `boolean` on
`POST`.

**location** `string`

Where the asker is. Perplexity answers a local question (`best dentist`,
`popular cafes`, `moving companies`) for this place. Without it, that place
is the exit's city, which changes from call to call (a `JP` exit can be in
Hamamatsu one call and Atsugi the next). Set it when you track a local
prompt, so every sample is about the same place.

A city from the list below, or `lat,lng` in decimal degrees (up to 8 decimal
places), e.g. `35.6812,139.7671`. Case does not matter, and spaces and
underscores count as hyphens: `New York` and `new_york` both mean
`new-york`. Any other value is a **`400`**, not billed. A JSON `string` on
`POST`.

It does not change the egress. `country` still picks the exit and the answer
language, so pair the two: `country=JP&location=tokyo`. Questions that are
not local are unaffected.

**Cities**

* **Japan:** `tokyo`, `yokohama`, `osaka`, `nagoya`, `sapporo`, `fukuoka`, `kyoto`, `kobe`, `sendai`, `hiroshima`
* **Asia-Pacific:** `seoul`, `busan`, `taipei`, `hong-kong`, `singapore`, `bangkok`, `hanoi`, `ho-chi-minh-city`, `jakarta`, `kuala-lumpur`, `manila`, `mumbai`, `delhi`, `bangalore`, `sydney`, `melbourne`
* **Americas:** `new-york`, `los-angeles`, `chicago`, `san-francisco`, `houston`, `miami`, `seattle`, `washington`, `toronto`, `vancouver`, `mexico-city`, `sao-paulo`, `buenos-aires`
* **Europe:** `london`, `manchester`, `paris`, `berlin`, `munich`, `hamburg`, `frankfurt`, `madrid`, `barcelona`, `rome`, `milan`, `amsterdam`, `brussels`, `vienna`, `zurich`, `lisbon`, `warsaw`, `istanbul`

**focus** `string` (default: web)

Retrieval focus: `web`, `scholar` (academic sources) or `social`
(discussions and forums).

## Response

**prompt** `string`

Echo of the prompt you sent.

**brand** `string`

Echo of the brand you tracked.

**domain** `string | null`

Echo of the domain you supplied.

**mentioned** `boolean`

Whether the brand (or any alias) appears in the answer.

**mention\_count** `integer`

How many times the brand or its aliases appear.

**first\_position** `integer | null`

Character offset of the first mention in `answer`. `null` when absent.

**position\_score** `number`

`1.0` = named at the very start of the answer, `0.0` = absent.

**share\_of\_voice\_pct** `number`

Brand mentions as a percentage of brand + competitor mentions.

**cited** `boolean`

Whether the brand's `domain` is among the cited sources.

**cited\_urls** `string[]`

The cited URLs on the brand's domain.

**citation\_rank** `integer | null`

1-based rank of the brand's first cited URL among all citations.

**competitors** `CompetitorMention[]`

One entry per competitor you named: `name`, `mentioned`, `mention_count`,
`first_position`, `cited`, `cited_urls`.

**excerpt** `string | null`

Answer text around the first brand mention.

**answer** `string`

The full answer text.

**citations** `Citation[]`

The sources the answer references, same shape as [`/ask`](https://docs.scrapebadger.com/api-reference/endpoint/perplexity/ask).

**web\_search\_triggered** `boolean`

Whether Perplexity searched the web.

**model** `string | null`

Which model answered.

**country** `string`

The market that actually answered. Without `strict_country` it can differ from the `country` you asked for.

**location** `string | null`

The `location` the ask was sent with, in canonical form, e.g. `tokyo` or `35.6812,139.7671`. `null` when you did not set one.

**latency\_ms** `integer`

End-to-end time in milliseconds.

**created\_utc** `number | null`

Answer creation time as a Unix timestamp.

**created\_at** `string | null`

Answer creation time as an ISO-8601 UTC string.

## Example

```bash cURL theme={null}
curl -G "https://scrapebadger.com/v1/perplexity/brand-visibility" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "prompt=What is the best web scraping API for e-commerce data?" \
  --data-urlencode "brand=ScrapeBadger" \
  --data-urlencode "domain=scrapebadger.com" \
  --data-urlencode "competitors=Bright Data,Oxylabs,Zyte" \
  --data-urlencode "country=US" \
  --max-time 120
```

```python Python theme={null}
import requests

res = requests.post(
    "https://scrapebadger.com/v1/perplexity/brand-visibility",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "prompt": "What is the best web scraping API for e-commerce data?",
        "brand": "ScrapeBadger",
        "domain": "scrapebadger.com",
        "competitors": ["Bright Data", "Oxylabs", "Zyte"],
        "country": "DE",
        "strict_country": True,
    },
    timeout=120,
)
data = res.json()
print(data["country"], data["mentioned"], data["share_of_voice_pct"])
```

## Strict country

By default `country` is best-effort, so a market that is short of exits still
gets an answer, from another market. Check the response `country` to see which
one answered. When the market matters more than the answer (local rankings,
per-country visibility tracking), set `strict_country=true`:

```bash theme={null}
curl -G "https://scrapebadger.com/v1/perplexity/brand-visibility" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "prompt=best electricity provider" \
  --data-urlencode "brand=Octopus Energy" \
  --data-urlencode "country=DE" \
  --data-urlencode "strict_country=true" \
  --max-time 120
```

If no exit in that market answers in time you get a `503`, which is not billed.
Retry later rather than dropping `strict_country`:

```json 503 Response theme={null}
{
  "detail": {
    "code": "country_unavailable",
    "message": "no DE exit answered in 16 attempts {...}; strict_country never falls back to another country"
  }
}
```

## Location

A local prompt, such as `best dentist`, gets an answer for the asker's city.
Without `location`, that is the exit's city, so the brands named change with
it between calls. Set `location` to track one place:

```bash theme={null}
curl -G "https://scrapebadger.com/v1/perplexity/brand-visibility" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "prompt=best moving company" \
  --data-urlencode "brand=Sakai Moving Center" \
  --data-urlencode "country=JP" \
  --data-urlencode "location=tokyo" \
  --max-time 120
```

The response carries `location` next to `country`. An unknown city or a
malformed `lat,lng` is a `400`, which is not billed:

```json 400 Response theme={null}
{
  "detail": "location must be a city (tokyo, osaka, seoul, new-york, london, ...) or 'lat,lng' in decimal degrees"
}
```


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