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.
Common name aliases work. Singular forms and natural synonyms resolve to the canonical facet — /v1/facets/niche → /niches, /techs (or /technology) → /technologies, /languages (or /language) → /language-codes, /currency → /currencies, /payment (or /payment-methods, /payment-providers, /gateways) → /payments, /brand-platform (or /ecommerce-platforms) → /brand-platforms, /countries → /country-codes, /tld → /tlds, /category → /categories, /sortable → /sortable-fields. Aliased responses are identical to the canonical route. Any other unknown facet name returns 404 facet_not_found with details.available_facets listing every valid facet.
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/brand-platforms | E-commerce platforms accepted by platform= / platform_exclude= on brands (shopify, woocommerce, prestashop, magento). Inputs are case-insensitive and common spellings are normalised. |
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, label?, icon_url?}. name is always the value you send back as a filter; label is an optional display-only override, present only where the raw name is unpresentable — render label when it is there, name otherwise, but always filter on name. 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/payments | Payment providers a store can accept, with icon URLs — wallets (Apple Pay, Shop Pay, Google Pay, PayPal), gateways (Stripe, Adyen, Mollie, Razorpay), buy-now-pay-later (Klarna, Afterpay, Affirm, Sezzle), in-store financing and recurring billing. Values feed the payments filter on brands. |
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, label?, icon_url?} plus a source field indicating where the dictionary was loaded from. Send name back as the filter value; show label instead when present.
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"
}