curl --request GET \
--url https://app.surfacd.com/api/v1/projects/{project}/brand-rankings \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.surfacd.com/api/v1/projects/{project}/brand-rankings"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.surfacd.com/api/v1/projects/{project}/brand-rankings', 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://app.surfacd.com/api/v1/projects/{project}/brand-rankings",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$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://app.surfacd.com/api/v1/projects/{project}/brand-rankings"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.surfacd.com/api/v1/projects/{project}/brand-rankings")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.surfacd.com/api/v1/projects/{project}/brand-rankings")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"domain": "<string>",
"type": 0,
"mentions_count": 123,
"total_responses": 123,
"visibility_score": 123,
"rank": 123,
"ranking_date": "2023-12-25",
"average_position": 123,
"previous_rank": 123,
"previous_visibility_score": 123,
"previous_mentions_count": 123,
"previous_average_position": 123,
"sentiment_score": 123,
"previous_sentiment_score": 123
}
],
"meta": {
"current_page": 123,
"last_page": 123,
"per_page": 123,
"total": 123,
"from": 123,
"links": [
{
"url": "<string>",
"label": "<string>",
"active": true
}
],
"path": "<string>",
"to": 123
},
"links": {
"first": "<string>",
"last": "<string>",
"prev": "<string>",
"next": "<string>"
}
}{
"message": "<string>",
"errors": {}
}Brand Rankings
Returns paginated brand rankings within a date range, with optional filters for brands, tags, services, countries, prompts, topics, and brand search. Each row includes visibility, mention-weighted sentiment score (0–100 Net Sentiment Index), mentions, and average position. Use brands with only_brand or always_include_brand to pin a specific brand.
curl --request GET \
--url https://app.surfacd.com/api/v1/projects/{project}/brand-rankings \
--header 'Authorization: Bearer <token>'import requests
url = "https://app.surfacd.com/api/v1/projects/{project}/brand-rankings"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://app.surfacd.com/api/v1/projects/{project}/brand-rankings', 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://app.surfacd.com/api/v1/projects/{project}/brand-rankings",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$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://app.surfacd.com/api/v1/projects/{project}/brand-rankings"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://app.surfacd.com/api/v1/projects/{project}/brand-rankings")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.surfacd.com/api/v1/projects/{project}/brand-rankings")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"domain": "<string>",
"type": 0,
"mentions_count": 123,
"total_responses": 123,
"visibility_score": 123,
"rank": 123,
"ranking_date": "2023-12-25",
"average_position": 123,
"previous_rank": 123,
"previous_visibility_score": 123,
"previous_mentions_count": 123,
"previous_average_position": 123,
"sentiment_score": 123,
"previous_sentiment_score": 123
}
],
"meta": {
"current_page": 123,
"last_page": 123,
"per_page": 123,
"total": 123,
"from": 123,
"links": [
{
"url": "<string>",
"label": "<string>",
"active": true
}
],
"path": "<string>",
"to": 123
},
"links": {
"first": "<string>",
"last": "<string>",
"prev": "<string>",
"next": "<string>"
}
}{
"message": "<string>",
"errors": {}
}Authorizations
Team API key created in Team Settings. Use it with URLs for the same team.
Path Parameters
Project UUID.
Query Parameters
Inclusive start of the reporting window. YYYY-MM-DD.
Inclusive end of the reporting window. YYYY-MM-DD. Must be on or after start_date.
x >= 11 <= x <= 100Brand UUID filter. Pass a single brand UUID as brands[]=....
1Tag UUID or name filters. Discover tags with GET /api/v1/projects/{project}/tags.
AI platform provider filters such as chatgpt or perplexity. Discover providers with GET /api/v1/platforms.
Country code filters such as US or GB. Discover codes with GET /api/v1/countries.
Prompt UUID filter.
Topic UUID or name filters. Use no_topic for prompts without a topic. Discover topics with GET /api/v1/projects/{project}/topics.
255When true, only the primary brand and marked competitors are included.
When true and brands contains one brand UUID, only that brand's ranking is returned.
When true and brands contains one brand UUID, the pinned brand is always included in the paginated result even if it would not otherwise appear on the current page.