curl --request GET \
--url https://api.syntalic.com/v1/social/attention-vs-shelfimport requests
url = "https://api.syntalic.com/v1/social/attention-vs-shelf"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.syntalic.com/v1/social/attention-vs-shelf', 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://api.syntalic.com/v1/social/attention-vs-shelf",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$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://api.syntalic.com/v1/social/attention-vs-shelf"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.syntalic.com/v1/social/attention-vs-shelf")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.syntalic.com/v1/social/attention-vs-shelf")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"category": "food-beverages-tobacco",
"country": "us",
"currency": "USD",
"window_days": 30,
"platform": "all",
"organic_only": false,
"brands": [
{
"brand": "Oreo",
"brand_key": "oreo",
"mentions": 21,
"attention_share_pct": 5.75,
"products": 9,
"shelf_share_pct": 0.03,
"gap_pct": 5.72,
"thin_base": false
},
{
"brand": "Starbucks",
"brand_key": "starbucks",
"mentions": 17,
"attention_share_pct": 4.66,
"products": 14,
"shelf_share_pct": 0.04,
"gap_pct": 4.62,
"thin_base": false
}
],
"corpus_mentions": 365,
"unmatched": {
"social_brands_not_on_shelf": 11,
"shelf_brands_not_in_conversation": 2074,
"note": "Joined on brand key, never on name. Unmatched rows are excluded from the ranking rather than fuzzy-matched, because a wrong join here mislabels a real brand as under-distributed."
},
"coverage": {
"social": {
"products": 151,
"sufficient": true
},
"social_counted": "brands",
"shelf": {
"products": 34482,
"sufficient": true
},
"shelf_counted": "products"
},
"freshness": {
"social": {
"observedThrough": "2026-11-16T06:26:37.000Z",
"staleHours": 58.1
},
"shelf_hours": null
},
"snapshot": {
"run_id": "d62295dc-6bb4-4d49-bb56-62432658a10a",
"lens_version": "social-publish-0.7",
"computed_at": "2026-11-16T12:42:25.858Z"
},
"resolved": null,
"meta": {
"served_from": "live",
"freshness_seconds": 34056,
"schema_version": "v3",
"computed_at": "2026-11-18T16:35:29.880Z"
}
}{
"type": "<string>",
"title": "Bad Request",
"status": 400,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Payment Required",
"status": 402,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Not Found",
"status": 404,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Conflict",
"status": 409,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Unprocessable Content",
"status": 422,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Too Many Requests",
"status": 429,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Internal Server Error",
"status": 500,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Service Unavailable",
"status": 503,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Rank brands by share-of-conversation vs share-of-shelf gap
Brands ranked by the GAP between share of social conversation and share of shelf inside one category. Over-indexed attention with under-distribution is the ranging signal a retail buyer wants and the deck slide a challenger brand wants - one endpoint, two customer types. Requires BOTH corpora bound to the same category axis and the same brand key, which is why nobody holding one of them can reproduce it. The join is on brand KEY, never on name: a row whose key is absent from the other side is dropped and COUNTED in unmatched, because matching by name mislabels a real brand as under-distributed. Carries TWO coverage blocks and TWO freshness values - social counts mention subjects on a weekly refresh, shelf counts products on a daily one, and merging either pair would be a lie with a familiar shape. shelf_brands_not_in_conversation is the mirror finding: stocked and unspoken of.
curl --request GET \
--url https://api.syntalic.com/v1/social/attention-vs-shelfimport requests
url = "https://api.syntalic.com/v1/social/attention-vs-shelf"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.syntalic.com/v1/social/attention-vs-shelf', 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://api.syntalic.com/v1/social/attention-vs-shelf",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$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://api.syntalic.com/v1/social/attention-vs-shelf"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.syntalic.com/v1/social/attention-vs-shelf")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.syntalic.com/v1/social/attention-vs-shelf")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"category": "food-beverages-tobacco",
"country": "us",
"currency": "USD",
"window_days": 30,
"platform": "all",
"organic_only": false,
"brands": [
{
"brand": "Oreo",
"brand_key": "oreo",
"mentions": 21,
"attention_share_pct": 5.75,
"products": 9,
"shelf_share_pct": 0.03,
"gap_pct": 5.72,
"thin_base": false
},
{
"brand": "Starbucks",
"brand_key": "starbucks",
"mentions": 17,
"attention_share_pct": 4.66,
"products": 14,
"shelf_share_pct": 0.04,
"gap_pct": 4.62,
"thin_base": false
}
],
"corpus_mentions": 365,
"unmatched": {
"social_brands_not_on_shelf": 11,
"shelf_brands_not_in_conversation": 2074,
"note": "Joined on brand key, never on name. Unmatched rows are excluded from the ranking rather than fuzzy-matched, because a wrong join here mislabels a real brand as under-distributed."
},
"coverage": {
"social": {
"products": 151,
"sufficient": true
},
"social_counted": "brands",
"shelf": {
"products": 34482,
"sufficient": true
},
"shelf_counted": "products"
},
"freshness": {
"social": {
"observedThrough": "2026-11-16T06:26:37.000Z",
"staleHours": 58.1
},
"shelf_hours": null
},
"snapshot": {
"run_id": "d62295dc-6bb4-4d49-bb56-62432658a10a",
"lens_version": "social-publish-0.7",
"computed_at": "2026-11-16T12:42:25.858Z"
},
"resolved": null,
"meta": {
"served_from": "live",
"freshness_seconds": 34056,
"schema_version": "v3",
"computed_at": "2026-11-18T16:35:29.880Z"
}
}{
"type": "<string>",
"title": "Bad Request",
"status": 400,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Payment Required",
"status": 402,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Not Found",
"status": 404,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Conflict",
"status": 409,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Unprocessable Content",
"status": 422,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Too Many Requests",
"status": 429,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Internal Server Error",
"status": 500,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"type": "<string>",
"title": "Service Unavailable",
"status": 503,
"detail": "<string>",
"instance": "<string>",
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Query Parameters
Shopify taxonomy path, as a join key or a display path: a root (food-beverages-tobacco) or any node under it. A brand is filed at one node and counted there and at every ancestor, so each depth is its own scope. A node no tracked brand sits under is refused free, with the published scopes that contain it. Retired browse roots (grocery-gourmet-food, ...) are refused with the root to use instead. The shelf side reads the same node, so both shares divide up one category. No wildcard: these answers are ranked comparisons.
Response
Attention vs shelf ranking