Implementation guide
1
Get your API key
You’ll need to create an account on our Developer Portal. Creating an account is quick and easy, and will give you access to your dashboard where you’ll find your API key.
2
Make your first API call
The Brand API supports multiple identifier types (domain, website URL, email address, Stock or ETF ticker, ISIN, Crypto symbol). Authentication is done by passing your API key as a Bearer Authentication.If you only have company names, use the Brand Search API to match brand names to the most likely URLs.
The shorthand route
/v2/brands/{identifier} (without a type prefix) is still supported and auto-detects the identifier type (in the order: domain → ticker → ISIN → crypto), but explicit type routes are recommended to avoid naming collisions.The API reads an identifier that contains @ as an email address and resolves it to its registrable domain. john@example.brandfetch.com returns the same response as brandfetch.com. The API does not store the address. Your request logs show only the resolved domain. Email addresses work on the shorthand route only.The API reads an identifier that starts with http:// or https:// (or the percent-encoded https%3A%2F%2F) as a website URL. The API also reads a domain with a path (brandfetch.com/developers/pricing) as a website URL. The API resolves the URL to the registrable domain of its host, so https://www.brandfetch.com/developers/pricing returns the same response as brandfetch.com. The API does not store the URL. Your request logs show only the resolved domain. Website URLs work on the shorthand route only.3
Test and deploy
All requests for the domain brandfetch.com are free and will not count towards your usage/quotas. You can make as many requests to the Brandfetch’s brand as you need while you iterate on and test your integration.Once you are ready to go live, replace brandfetch.com with the identifier you want to look up: a domain name, website URL, email address, Stock/ETF ticker, ISIN, or Crypto symbol.
Prefetching brands
Brand API works in real time: the first request for a brand nobody has asked for before crawls it live, which may take a moment. When you know ahead of time which brand you will need — a user has just signed up, and their brand screen is a few steps away — ask for it in advance with aHEAD request on the same route:
Prefetch at signup
HEAD accepts every identifier the GET does — a domain, an email address, a brand ID, a ticker, an ISIN or a crypto symbol. Prefetch requests never count towards your quota. Prefetch requests may be throttled to prevent abuse and ensure quality of service. See the reference for the full contract.
Skip crawling (cached only)
By default, a brand that is not yet part of the dataset is indexed live. This guarantees global coverage, but a live crawl can take several seconds. A crawl still running when the request has to be answered carries on in the background, and the request is answered404 with the header x-bf-error: crawl_queued: retry in a minute or two; if the brand could be collected, it is served.
When latency matters more than coverage, such as enriching records in bulk or rendering a screen that cannot wait, set the cachedOnly query parameter to true. The API then answers from its store alone, instantly and without crawling:
- A brand that is already indexed is returned immediately (
200), exactly as a normal request would return it. - A brand that is not yet indexed is answered with
204 No Contentinstead of being crawled live.
cachedOnly works on every GET /v2/brands route and with every identifier type. On a ticker, ISIN, or crypto symbol that is not yet indexed, the API skips the identifier resolution too and answers 204. A 204 has no body, so check the status code before parsing the response. A 204 does not count towards your quota.
To index a brand ahead of time, make a standard request without cachedOnly, or prefetch it with a HEAD request. Once the brand is indexed, cachedOnly=true requests return it instantly.
Color palette (beta)
Every brand response carriescolors: the brand’s accent, dark, and light colors. Add palette=true to a Brand API request to get the brand’s full color system. palette=1 does the same:
Palette
palette. The rest of the response does not change. A request without the parameter, or with another value, does not change.
The palette object holds:
colors: the ranked colors. Each color has arolesuch asprimaryorbackground, and acontextofidentity,interface, orboth. Each color also has the text color that reads best on it.onPairs: the background and text pairs that the brand’s website uses, with their WCAG contrast.themes: the light and dark themes that the website showed.gradients: the gradients in the brand’s stylesheets.logos: the colors of each logo and icon.
usage: the elements that the website paints with the color, such asbuttonbackgrounds orlinktext, with counts and example labels. This is the field to read when you want to know what a color is for.tokens: the website’s own CSS variable names for the color, such ashds-color-core-brand-500.variants: the near-identical HEX codes that Brandfetch merged into the color.
primary. An integration that shows one brand color has nothing to show for that brand.
A color that only a theme, gradient, on-pair, or logo references is also in colors, with rank: null and member: true. To get the brand colors alone, keep the colors with a rank.
If a brand has no palette yet, the first request builds one from the brand’s last crawl and stores it. This first request can take some seconds longer. Later requests get the stored palette. A palette built this way has no new render, so themes and onPairs can be empty. The next crawl of the brand replaces it.
The palette is in beta. Its shape can change.
palette is null in three cases: Brandfetch has no crawl to build one from, the brand has isNsfw: true, or the build did not finish in time for this response. In the last case, a later request tries again. The colors array does not change and stays the stable choice for existing integrations.Quotas and usage
When you sign up for a free developer account, you get 100 free requests.HEAD requests (see Prefetching brands) and 204 responses to cachedOnly requests (see Skip crawling) are not counted. If you need to make more requests, please upgrade to a paid plan. When upgrading, you can confirm your quota by looking at the x-api-key-quota response header. To see your current month’s usage, look for the x-api-key-approximate-usage response header.
We will also send you an email warning you upon reaching 80% of your quota. The API will return an HTTP status code 429 when the quota has been reached.
In addition to a usage quota we also apply a request throughput limit to protect our service from abuse. By default, throughput is limited to a sustained 100 requests/second with some flexibility to accommodate bursts (30,000 requests / rolling 5 minute hard limit). You’ll receive an HTTP status code 429 when you exceed this limit.
If your use-case requires higher throughput limits, contact us.