Facets
The facets endpoints return the canonical list of values accepted by the rest of the API — niches, ad platforms, sort keys, field names. Use them to build dropdowns, validate input on your end, or stay in sync as the taxonomy evolves.
All facets endpoints are unmetered — free to call, with X-Quota-Charged: false in every response.
Schema facets
These return the canonical values used by other endpoints' filter, sort, and projection parameters. Each returns {"values": [...]} (or a dict of resource → list).
| Endpoint | Returns |
|---|---|
GET /v1/facets/niches | The 20 niche values accepted in niche and niche_exclude on /v1/brands. |
GET /v1/facets/platforms | Values accepted by platform= on /v1/brands/{id}/ads (meta, tiktok, instagram). |
GET /v1/facets/meta-platforms | Meta sub-platforms accepted by platforms= on /v1/meta-ads/search (lowercase canonical: facebook, instagram, messenger, audience_network, threads). Inputs are case-insensitive. |
GET /v1/facets/genders | Values accepted by target_gender= on /v1/meta-ads/search. |
GET /v1/facets/sortable-fields | Sort keys per resource (brands, meta_ads, tiktok_ads, instagram_posts). |
GET /v1/facets/fields | Field names accepted by fields= and exclude_fields= per resource (brands, meta_ads, tiktok_ads, instagram_posts, products). |
Reference data facets
These return canonical reference data used to interpret brand fields — tech stacks, currencies, country codes, themes, etc. Items are normalized to {name, icon_url?}. Each response also includes a source field — upstream when the latest dictionary was loaded, or vendored when a built-in copy was used as a fallback (the live dictionary was temporarily unreachable).
| Endpoint | Returns |
|---|---|
GET /v1/facets/technologies | Tech-stack values (Shopify, Stripe, Klaviyo, Printful, GA4, …) with icon URLs. |
GET /v1/facets/apps | Shopify-app store entries with icon URLs (Klaviyo, Judge.me, …). |
GET /v1/facets/pixels | The 10 canonical tracking pixels (Facebook, TikTok, Pinterest, …). |
GET /v1/facets/premium-pixels | Premium tracking apps (Triple Whale, Hyros, wetracked.io, …). |
GET /v1/facets/categories | Commerce categories (e.g., /Apparel/Clothing Accessories). |
GET /v1/facets/country-codes | ISO-3166 country codes. |
GET /v1/facets/country-names | Country names (matches country-codes). |
GET /v1/facets/currencies | ISO-4217 currency codes. |
GET /v1/facets/language-codes | ISO-639 language codes. |
GET /v1/facets/tlds | Top-level domain extensions. |
GET /v1/facets/themes | Shopify theme names. |
Example — list niches
Returns the canonical niche taxonomy as a sorted array.
Request
curl https://api.brandsearch.co/v1/facets/niches \
-H "X-API-Key: bsk_your_api_key"
Response
{
"values": [
"Arts & Crafts",
"Automotive",
"Baby & Kids",
"Beauty & Skincare",
"Books & Education",
"Electronics & Tech",
"Fashion",
"Food & Drink",
"Furniture",
"Gaming",
"Health & Supplements",
"Home & Garden",
"Home Decor",
"Jewelry",
"Kitchen",
"Music & Instruments",
"Other",
"Pet Supplies",
"Sports & Outdoors",
"Toys & Games"
]
}
Example — list sortable fields
Returns sort keys grouped by resource.
Request
curl https://api.brandsearch.co/v1/facets/sortable-fields \
-H "X-API-Key: bsk_your_api_key"
Response (truncated)
{
"brands": ["combined_followers", "created_at", "estimated_sales", "..."],
"meta_ads": ["created_at", "duration", "eu_total_reach", "..."],
"tiktok_ads": ["comment_count", "create_time", "digg_count", "..."],
"instagram_posts": ["comment_count", "engagement_rate", "like_count", "..."]
}
Example — list technologies
Reference-data facets return items as {name, icon_url?} plus a source field indicating where the dictionary was loaded from.
Request
curl https://api.brandsearch.co/v1/facets/technologies \
-H "X-API-Key: bsk_your_api_key"
Response (truncated)
{
"values": [
{ "name": "Shopify", "icon_url": "https://..." },
{ "name": "Klaviyo", "icon_url": "https://..." },
{ "name": "GA4", "icon_url": "https://..." }
],
"source": "upstream"
}