Skip to main content
POST
/
products
/
attributes
Get Shopping Attributes
curl --request POST \
  --url https://api.peec.ai/customer/v1/products/attributes \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "project_id": "or_f45b94ba-5e35-4982-93ed-285e72ee14eb",
  "start_date": "2025-09-22",
  "end_date": "2025-09-22",
  "previous_start_date": "2023-12-25",
  "previous_end_date": "2023-12-25",
  "scope": "product",
  "compare_by": "brand",
  "tab": "characteristics",
  "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "category_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "country_codes": [],
  "model_ids": [],
  "model_channel_ids": [],
  "topic_ids": [
    "<string>"
  ],
  "tag_ids": [
    "<string>"
  ],
  "search": "<string>",
  "competitor_count": 10,
  "values_per_group": 25,
  "limit": 50,
  "offset": 4503599627370495
}
'
import requests

url = "https://api.peec.ai/customer/v1/products/attributes"

payload = {
    "project_id": "or_f45b94ba-5e35-4982-93ed-285e72ee14eb",
    "start_date": "2025-09-22",
    "end_date": "2025-09-22",
    "previous_start_date": "2023-12-25",
    "previous_end_date": "2023-12-25",
    "scope": "product",
    "compare_by": "brand",
    "tab": "characteristics",
    "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "category_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "country_codes": [],
    "model_ids": [],
    "model_channel_ids": [],
    "topic_ids": ["<string>"],
    "tag_ids": ["<string>"],
    "search": "<string>",
    "competitor_count": 10,
    "values_per_group": 25,
    "limit": 50,
    "offset": 4503599627370495
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    project_id: 'or_f45b94ba-5e35-4982-93ed-285e72ee14eb',
    start_date: '2025-09-22',
    end_date: '2025-09-22',
    previous_start_date: '2023-12-25',
    previous_end_date: '2023-12-25',
    scope: 'product',
    compare_by: 'brand',
    tab: 'characteristics',
    product_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    category_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    country_codes: [],
    model_ids: [],
    model_channel_ids: [],
    topic_ids: ['<string>'],
    tag_ids: ['<string>'],
    search: '<string>',
    competitor_count: 10,
    values_per_group: 25,
    limit: 50,
    offset: 4503599627370495
  })
};

fetch('https://api.peec.ai/customer/v1/products/attributes', 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.peec.ai/customer/v1/products/attributes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'project_id' => 'or_f45b94ba-5e35-4982-93ed-285e72ee14eb',
    'start_date' => '2025-09-22',
    'end_date' => '2025-09-22',
    'previous_start_date' => '2023-12-25',
    'previous_end_date' => '2023-12-25',
    'scope' => 'product',
    'compare_by' => 'brand',
    'tab' => 'characteristics',
    'product_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'category_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'country_codes' => [
        
    ],
    'model_ids' => [
        
    ],
    'model_channel_ids' => [
        
    ],
    'topic_ids' => [
        '<string>'
    ],
    'tag_ids' => [
        '<string>'
    ],
    'search' => '<string>',
    'competitor_count' => 10,
    'values_per_group' => 25,
    'limit' => 50,
    'offset' => 4503599627370495
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.peec.ai/customer/v1/products/attributes"

	payload := strings.NewReader("{\n  \"project_id\": \"or_f45b94ba-5e35-4982-93ed-285e72ee14eb\",\n  \"start_date\": \"2025-09-22\",\n  \"end_date\": \"2025-09-22\",\n  \"previous_start_date\": \"2023-12-25\",\n  \"previous_end_date\": \"2023-12-25\",\n  \"scope\": \"product\",\n  \"compare_by\": \"brand\",\n  \"tab\": \"characteristics\",\n  \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"category_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"country_codes\": [],\n  \"model_ids\": [],\n  \"model_channel_ids\": [],\n  \"topic_ids\": [\n    \"<string>\"\n  ],\n  \"tag_ids\": [\n    \"<string>\"\n  ],\n  \"search\": \"<string>\",\n  \"competitor_count\": 10,\n  \"values_per_group\": 25,\n  \"limit\": 50,\n  \"offset\": 4503599627370495\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.peec.ai/customer/v1/products/attributes")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"project_id\": \"or_f45b94ba-5e35-4982-93ed-285e72ee14eb\",\n  \"start_date\": \"2025-09-22\",\n  \"end_date\": \"2025-09-22\",\n  \"previous_start_date\": \"2023-12-25\",\n  \"previous_end_date\": \"2023-12-25\",\n  \"scope\": \"product\",\n  \"compare_by\": \"brand\",\n  \"tab\": \"characteristics\",\n  \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"category_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"country_codes\": [],\n  \"model_ids\": [],\n  \"model_channel_ids\": [],\n  \"topic_ids\": [\n    \"<string>\"\n  ],\n  \"tag_ids\": [\n    \"<string>\"\n  ],\n  \"search\": \"<string>\",\n  \"competitor_count\": 10,\n  \"values_per_group\": 25,\n  \"limit\": 50,\n  \"offset\": 4503599627370495\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.peec.ai/customer/v1/products/attributes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"project_id\": \"or_f45b94ba-5e35-4982-93ed-285e72ee14eb\",\n  \"start_date\": \"2025-09-22\",\n  \"end_date\": \"2025-09-22\",\n  \"previous_start_date\": \"2023-12-25\",\n  \"previous_end_date\": \"2023-12-25\",\n  \"scope\": \"product\",\n  \"compare_by\": \"brand\",\n  \"tab\": \"characteristics\",\n  \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"category_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"country_codes\": [],\n  \"model_ids\": [],\n  \"model_channel_ids\": [],\n  \"topic_ids\": [\n    \"<string>\"\n  ],\n  \"tag_ids\": [\n    \"<string>\"\n  ],\n  \"search\": \"<string>\",\n  \"competitor_count\": 10,\n  \"values_per_group\": 25,\n  \"limit\": 50,\n  \"offset\": 4503599627370495\n}"

response = http.request(request)
puts response.read_body
{
  "competitors": [
    {
      "global_brand_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "domain": "<string>",
      "mentions": 123
    }
  ],
  "total_groups": 123,
  "tab": "characteristics",
  "groups": [
    {
      "dimension_id": "<string>",
      "name": "<string>",
      "total_mentions": 123,
      "total_mentions_delta": 123,
      "value_count": 123,
      "values": [
        {
          "value": "<string>",
          "mentions": 123,
          "mentions_delta": 123,
          "competitor_mentions": [
            123
          ]
        }
      ]
    }
  ]
}

Authorizations

​
X-API-Key
string
header
required

Body

​
project_id
string

Required if using a company api key

Example:

"or_f45b94ba-5e35-4982-93ed-285e72ee14eb"

​
start_date
string<date>
default:2026-01-01

full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
Example:

"2025-09-22"

​
end_date
string<date>
default:2026-01-01

full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
Example:

"2025-09-22"

​
previous_start_date
string<date>

Start of an explicit comparison window for deltas. Provide together with previous_end_date, or omit both to auto-derive an equal-length window immediately before [start_date, end_date].

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
​
previous_end_date
string<date>

End of the explicit comparison window. Provide together with previous_start_date, or omit both to auto-derive.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
​
scope
enum<string>
default:product

product compares one product (needs product_id); overview compares the whole catalog.

Available options:
product,
overview
​
compare_by
enum<string>
default:brand

Grid columns: competing brands, or competing products. product is only valid when scope=product.

Available options:
brand,
product
​
tab
enum<string>
default:characteristics

characteristics (qualitative values), facts (true/false), dimensions (ordinal ratings).

Available options:
characteristics,
facts,
dimensions
​
product_id
string<uuid>

Required when scope=product.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
​
category_ids
string<uuid>[]
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
​
country_codes
enum<string>[]
Available options:
AE,
AL,
AM,
AR,
AT,
AU,
BA,
BE,
BG,
BH,
BO,
BR,
BS,
BY,
CA,
CH,
CL,
CN,
CO,
CR,
CY,
CZ,
DE,
DK,
DO,
EC,
EE,
EG,
ES,
FI,
FR,
GB,
GE,
GH,
GR,
GT,
HK,
HN,
HR,
HU,
ID,
IE,
IL,
IN,
IQ,
IS,
IT,
JO,
JP,
KR,
KW,
LB,
LI,
LT,
LU,
LV,
MA,
MD,
ME,
MK,
MT,
MX,
MY,
NG,
NI,
NL,
NO,
NZ,
OM,
PK,
PA,
PE,
PH,
PL,
PT,
PY,
PS,
QA,
RO,
RS,
SA,
SE,
SG,
SI,
SK,
SV,
TH,
TN,
TR,
TW,
UA,
US,
UY,
VE,
VN,
ZA,
AD,
AF,
AS,
AZ,
BB,
BQ,
CG,
CI,
CM,
CW,
DM,
DZ,
FO,
GF,
GP,
JM,
KG,
KH,
KI,
KZ,
LK,
LR,
LS,
MW,
NC,
PG,
TD,
TF,
UG,
VU,
ZW
​
model_ids
enum<string>[]
Available options:
chatgpt,
microsoft-copilot,
sonar-api,
grok-api,
gpt-4o-search,
sonar,
google-ai-overview,
google-ai-mode,
gemini-2-5-flash,
gemini-3-1-flash-lite,
gemini-3-1-flash-lite-search,
claude-sonnet-4,
claude-sonnet-4-6,
claude-haiku-4-5,
grok-2-1212,
gpt-4o,
qwen-3-6-plus,
qwen-3-7-plus,
gpt-3-5-turbo,
gemini-1-5-flash,
deepseek-r1,
deepseek-v4-pro,
llama-3-3-70b-instruct,
gpt-5-1,
gemini-2-5-flash-preview-05-20,
claude-3-5-sonnet,
chatgpt-ui,
gpt-5-search,
gpt-5-6-luna,
perplexity-ui,
gemini-ui,
grok-4,
grok-4-3,
grok-ui,
microsoft-copilot-ui,
claude-3-5-haiku,
llama-3-1-sonar-small-128k-online,
amazon-rufus,
mistral-small-4,
mistral-medium-3-5
​
model_channel_ids
enum<string>[]
Available options:
openai-0,
openai-1,
qwen-0,
openai-2,
perplexity-0,
perplexity-1,
google-0,
google-1,
google-2,
google-3,
google-4,
anthropic-0,
anthropic-1,
deepseek-0,
meta-0,
xai-0,
xai-1,
microsoft-0,
amazon-0,
mistral-0,
mistral-1
​
topic_ids
string[]
​
tag_ids
string[]
​
tag_operator
enum<string>
Available options:
and,
or
​
search
string

Substring match on dimension name (and value, characteristics).

​
competitor_count
integer

Grid columns; default 6. 0 disables competitor lookup.

Required range: 0 <= x <= 20
​
values_per_group
integer

Characteristics tab only; default 12.

Required range: 1 <= x <= 50
​
limit
integer

Page size over dimension groups.

Required range: 1 <= x <= 100
​
offset
integer
Required range: 0 <= x <= 9007199254740991

Response

200 - application/json

Response for status 200

​
competitors
object[]
required
​
total_groups
number
required
​
tab
enum<string>
required
Available options:
characteristics
​
groups
object[]
required