Brand Visibility
curl --request GET \
--url https://scrapebadger.com/v1/perplexity/brand-visibility \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://scrapebadger.com/v1/perplexity/brand-visibility"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://scrapebadger.com/v1/perplexity/brand-visibility', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://scrapebadger.com/v1/perplexity/brand-visibility",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://scrapebadger.com/v1/perplexity/brand-visibility"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://scrapebadger.com/v1/perplexity/brand-visibility")
.header("X-API-Key", "<x-api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://scrapebadger.com/v1/perplexity/brand-visibility")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body{
"prompt": "<string>",
"brand": "<string>",
"domain": {},
"mentioned": true,
"mention_count": 123,
"first_position": {},
"position_score": 123,
"share_of_voice_pct": 123,
"cited": true,
"cited_urls": [
"<string>"
],
"citation_rank": {},
"competitors": [
{}
],
"excerpt": {},
"answer": "<string>",
"citations": [
{}
],
"web_search_triggered": true,
"model": {},
"country": "<string>",
"location": {},
"latency_ms": 123,
"created_utc": {},
"created_at": {}
}Brand Visibility
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.
GET
/
v1
/
perplexity
/
brand-visibility
Brand Visibility
curl --request GET \
--url https://scrapebadger.com/v1/perplexity/brand-visibility \
--header 'X-API-Key: <x-api-key>'import requests
url = "https://scrapebadger.com/v1/perplexity/brand-visibility"
headers = {"X-API-Key": "<x-api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<x-api-key>'}};
fetch('https://scrapebadger.com/v1/perplexity/brand-visibility', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://scrapebadger.com/v1/perplexity/brand-visibility",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://scrapebadger.com/v1/perplexity/brand-visibility"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<x-api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://scrapebadger.com/v1/perplexity/brand-visibility")
.header("X-API-Key", "<x-api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://scrapebadger.com/v1/perplexity/brand-visibility")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<x-api-key>'
response = http.request(request)
puts response.read_body{
"prompt": "<string>",
"brand": "<string>",
"domain": {},
"mentioned": true,
"mention_count": 123,
"first_position": {},
"position_score": 123,
"share_of_voice_pct": 123,
"cited": true,
"cited_urls": [
"<string>"
],
"citation_rank": {},
"competitors": [
{}
],
"excerpt": {},
"answer": "<string>",
"citations": [
{}
],
"web_search_triggered": true,
"model": {},
"country": "<string>",
"location": {},
"latency_ms": 123,
"created_utc": {},
"created_at": {}
}Ask the real
If no exit in that market answers in time you get a
The response carries
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
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
Query Parameters
The question to ask, typically a buyer-intent prompt like
best web scraping API for e-commerce. Maximum 4,096 characters.Alternate spellings that also count as a mention of
brand.
Comma-separated on GET; a string[] on POST.Competitor names to measure against, e.g.
Bright Data,Oxylabs,Zyte.
Comma-separated on GET; a string[] on POST.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.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.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.Show Cities
Show 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
Retrieval focus:
web, scholar (academic sources) or social
(discussions and forums).Response
One entry per competitor you named:
name, mentioned, mention_count,
first_position, cited, cited_urls.The sources the answer references, same shape as
/ask.The market that actually answered. Without
strict_country it can differ from the country you asked for.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.Example
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
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 defaultcountry 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:
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
503, which is not billed.
Retry later rather than dropping strict_country:
503 Response
{
"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 asbest 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:
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
location next to country. An unknown city or a
malformed lat,lng is a 400, which is not billed:
400 Response
{
"detail": "location must be a city (tokyo, osaka, seoul, new-york, london, ...) or 'lat,lng' in decimal degrees"
}

