Top Trends

GET /v1/latest/{level}/trends/{limit}/popindex/{region}/{category_id}

Returns the most popular items for a category in a given region, ranked by popularity index.

Parameters

Name	Type	Required	Description
`level`	`string`	yes	Categorisation level. One of `cat1, cat2`.
`limit`	`string`	yes	Number of rows to return. One of `top5, all`.
`region`	`string`	yes	Region code for the market you want data from. One of `us, gb, fr, kr, jp, global`.
`category_id`	`UUID`	yes	Identifier of the category you want trends for.

Response

Root

Field	Type	Description
`key`	`string`	The API resource key identifying the request path.
`credits_used`	`integer`	Number of API credits consumed for the request.
`data`	`object`	Contains trend data and metadata for the category.

Data

Field	Type	Description
`cat{N}_id`	`string`	Unique identifier for the category. One of `cat1_id, cat2_id, cat3_id`
`dashboard`	`string`	URL to the interactive dashboard for this category on Spate.
`trends`	`array`	List of the top 5 trend items relating to the specified category.
`call_cost`	`integer`	Credits used to make this API call.
`data_cost`	`integer`	Estimated data cost in credits.

Trends

Each item in the array represents a specific trend at the cat5 level.

Field	Type	Description
`cat5_id`	`string`	Unique identifier for the sub-category or trend.
`cat5_label`	`string`	Descriptive label of the trend, e.g., “hairstyle”, “perfume”.
`rank`	`integer`	Rank among the top 5 trends (1 = highest).
`life_cycle`	`string`	Current lifecycle stage of the trend (e.g., “mainstream”, “emerging”, ).
`popularity`	`integer`	Aggregate popularity score for the trend.
`yoy_percent_increase`	`float`	Year-over-year percentage trend change. Negative values indicate a decrease.
`yoy_absolute_increase`	`integer`	Year-over-year absolute change in popularity.
`qoq_percent_increase`	`float`	Quarter-over-quarter percentage change.
`qoq_absolute_increase`	`integer`	Quarter-over-quarter absolute change in popularity.
`mom_percent_increase`	`float`	Month-over-month percentage change.
`mom_absolute_increase`	`integer`	Month-over-month absolute change in popularity.
`yoy_percent_increase_prediction`	`float`	Predicted Year-over-year percentage change for upcoming periods.
`google_share_percent`	`float`	Fraction of total share volume from Google.
`tiktok_share_percent`	`float`	Fraction of total share volume from TikTok.
`instagram_share_percent`	`float`	Fraction of total share volume from Instagram.
`cluster`	`string`	Classification label for the trend (e.g., “sustained riser”, “sustained decliner”).

Examples

Top 5 Beauty trends

Request

curl "https://api.spate.nyc/v1/latest/cat1/trends/top5/popindex/us/6d408533-6979-43aa-80af-4d88bf0be860" \
    -H "Authorization: Bearer $SPATE_API_KEY" | jq

const id = "6d408533-6979-43aa-80af-4d88bf0be860";
const res = await fetch(
  `https://api.spate.nyc/v1/latest/cat1/trends/top5/popindex/us/${id}`,
  {
    headers: { Authorization: `Bearer ${process.env.SPATE_API_KEY}` },
  },
);

if (!res.ok) throw new Error(`Spate ${res.status}: ${await res.text()}`);
const { data } = await res.json();

import os
import requests

cat1_id = "6d408533-6979-43aa-80af-4d88bf0be860"
res = requests.get(
    f"https://api.spate.nyc/v1/latest/cat1/trends/top5/popindex/us/{cat1_id}",
    headers={"Authorization": f"Bearer {os.environ['SPATE_API_KEY']}"},
    timeout=10,
)
res.raise_for_status()
payload = res.json()

Response

{
  "key": "/v1/2026w21/cat1/trends/top5/popindex/us/6d408533-6979-43aa-80af-4d88bf0be860",
  "credits_used": 35,
  "data": {
    "cat1_id": "6d408533-6979-43aa-80af-4d88bf0be860",
    "dashboard": "https://app.spate.nyc/explore/trends/6d408533-6979-43aa-80af-4d88bf0be860?country=US",
    "trends": [
      {
        "cat5_id": "516b0050-658f-4057-bd04-24fc8a522a50",
        "cat5_label": "hairstyle",
        "rank": 1,
        "life_cycle": null,
        "popularity": 1257365652,
        "yoy_percent_increase": -0.157456,
        "yoy_absolute_increase": -234977721,
        "qoq_percent_increase": -0.11164,
        "qoq_absolute_increase": -133264313,
        "mom_percent_increase": -0.199691,
        "mom_absolute_increase": -217511533,
        "yoy_percent_increase_prediction": -0.21054,
        "google_share_percent": 0.57076,
        "tiktok_share_percent": 0.300384,
        "instagram_share_percent": 0.128856,
        "cluster": "sustained decliner"
      },
      ...
    ],
    "call_cost": 10,
    "data_cost": 25
  }
}