curl --request GET \
--url https://api.syntalic.com/v1/marketing/promo-intelligenceimport requests
url = "https://api.syntalic.com/v1/marketing/promo-intelligence"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.syntalic.com/v1/marketing/promo-intelligence', 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/marketing/promo-intelligence",
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/marketing/promo-intelligence"
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/marketing/promo-intelligence")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.syntalic.com/v1/marketing/promo-intelligence")
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": "<string>",
"country": "<string>",
"currency": "<string>",
"retailer": "<string>",
"brand": "<string>",
"aggregate_by": "brand",
"window": {
"preset": "<string>",
"from": "2023-12-25",
"to": "2023-12-25",
"granularity": "<string>",
"comparison_from": "2023-12-25",
"comparison_to": "2023-12-25",
"timezone": "UTC"
},
"brands": [
{
"brand": "<string>",
"retailer": "<string>",
"total_observations": 123,
"promo_observations": 123,
"promo_frequency_pct": 123,
"avg_promo_depth_pct": 123,
"max_promo_depth_pct": 123
}
],
"retailers": [
{
"brand": "<string>",
"retailer": "<string>",
"total_observations": 123,
"promo_observations": 123,
"promo_frequency_pct": 123,
"avg_promo_depth_pct": 123,
"max_promo_depth_pct": 123
}
],
"resolved": {
"input": "<string>",
"category_path": "<string>",
"department": "<string>",
"match_source": "<string>",
"match_confidence": 123,
"alternates": [
{}
]
},
"meta": {
"served_from": "<string>",
"freshness_seconds": 123,
"schema_version": "<string>",
"computed_at": "2023-11-07T05:31:56Z",
"price_observed_at_min": "2023-11-07T05:31:56Z",
"price_observed_at_max": "2023-11-07T05:31:56Z"
}
}{
"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": "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": {}
}
}Analyze promotional activity in a category
Analyze promotional activity within a category - promo frequency, average and max discount depth - over a date range. Pivot the breakdown with aggregate_by: default brand ranks brands within the category; retailer ranks retailers (use together with brand=<name> to answer ‘which retailers run the deepest promos on Brand X in Category Y’). The response key mirrors the dimension: brands: [...] or retailers: [...].
curl --request GET \
--url https://api.syntalic.com/v1/marketing/promo-intelligenceimport requests
url = "https://api.syntalic.com/v1/marketing/promo-intelligence"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.syntalic.com/v1/marketing/promo-intelligence', 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/marketing/promo-intelligence",
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/marketing/promo-intelligence"
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/marketing/promo-intelligence")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.syntalic.com/v1/marketing/promo-intelligence")
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": "<string>",
"country": "<string>",
"currency": "<string>",
"retailer": "<string>",
"brand": "<string>",
"aggregate_by": "brand",
"window": {
"preset": "<string>",
"from": "2023-12-25",
"to": "2023-12-25",
"granularity": "<string>",
"comparison_from": "2023-12-25",
"comparison_to": "2023-12-25",
"timezone": "UTC"
},
"brands": [
{
"brand": "<string>",
"retailer": "<string>",
"total_observations": 123,
"promo_observations": 123,
"promo_frequency_pct": 123,
"avg_promo_depth_pct": 123,
"max_promo_depth_pct": 123
}
],
"retailers": [
{
"brand": "<string>",
"retailer": "<string>",
"total_observations": 123,
"promo_observations": 123,
"promo_frequency_pct": 123,
"avg_promo_depth_pct": 123,
"max_promo_depth_pct": 123
}
],
"resolved": {
"input": "<string>",
"category_path": "<string>",
"department": "<string>",
"match_source": "<string>",
"match_confidence": 123,
"alternates": [
{}
]
},
"meta": {
"served_from": "<string>",
"freshness_seconds": 123,
"schema_version": "<string>",
"computed_at": "2023-11-07T05:31:56Z",
"price_observed_at_min": "2023-11-07T05:31:56Z",
"price_observed_at_max": "2023-11-07T05:31:56Z"
}
}{
"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": "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": {}
}
}Query Parameters
Product category. Accepts a human-readable name (e.g. 'electronics', 'beauty') or a taxonomy slug path (e.g. 'electronics/headphones'); matched against the catalog's category tree (exact node, subtree, or path substring). Also accepts a GS1 GPC code (exactly 8 digits, e.g. '10001159') to filter by PRODUCT TYPE instead of by shelf placement — the same product type is shelved under different categories by different retailers, so a category filter answers from a fraction of the data while a GPC code spans them. Coarser codes (class/family/segment) match every brick beneath them. Resolve a phrase to a code with /v1/reference/classify?q=... ; when a code is used, resolved.match_source is 'gpc'.
1Country (us or ca)
us, ca Filter to a specific retailer platform (long-tail specialty stores are also present; any platform key is accepted)
amazon, walmart, target, bestbuy, homedepot, costco, ikea, samsclub, cvs, dillards Optional brand filter — limit aggregation to products of this brand (case-insensitive)
1Group-by dimension. brand (default) ranks brands within the category. retailer ranks retailers — pair with brand to answer 'which retailers run the deepest promos on Brand X'.
brand, retailer Historical window preset. Explicit from/to takes precedence and is reported as custom; time_window=custom requires both from and to. Date-only ranges use UTC calendar boundaries with inclusive from and exclusive to.
last_30_days, last_60_days, last_90_days, month_to_date, previous_month, month_over_month, quarter_to_date, custom Start date (ISO 8601, defaults to 30 days ago)
End date (ISO 8601, defaults to now)
Response
Promo intelligence
brand, retailer Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes

