> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brandfetch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Brand Search API

> Match brand names to their domain and logo

[Brand Search API](https://brandfetch.com/developers/brand-search-api) provides fast querying of brands. It lets you search by brand names and match them to their corresponding URLs, enabling you to create rich autocomplete experiences.

The Brand Search API is designed to work in tandem with our other services. Once a user selects a brand, you can use its unique identifier to retrieve detailed data using our other APIs.

## Implementation guide

<Steps>
  <Step title="Get your client ID">
    You’ll need to create an account on our [Developer Portal](https://developers.brandfetch.com/register). Creating an account is quick and easy, and will give you access to your dashboard where you’ll find your client ID.
  </Step>

  <Step title="Make your first API call">
    <Tip>
      Brand Search API is free to use and <u>we don't ask for any attribution</u>.
    </Tip>

    Implement or run the code below to make your first API request.

    <CodeGroup>
      ```curl curl theme={null}
      curl --request GET \
      --url "https://api.brandfetch.io/v2/search/:name?c=BRANDFETCH_CLIENT_ID"
      ```
    </CodeGroup>

    Authentication is done by passing your client ID as a query parameter.
  </Step>

  <Step title="Test and deploy">
    The Brand Search API is a free product. Before you deploy your application to a live environment, be sure to consult our [rate limits](#rate-limits) and review our [usage guidelines](#usage-guidelines) to ensure a smooth launch.
  </Step>
</Steps>

## Usage guidelines

<AccordionGroup>
  <Accordion title="Authentication" defaultOpen="true">
    **To use Brand Search API, you must include your client ID with every request.**

    Adding your client ID provides reliable access, supports fair usage, and keeps consistent performance across all requests.

    [Create a free account](https://developers.brandfetch.com/register) and access your client ID from the Developer Portal.

    To use Brand Search API, include your client ID with every request as shown below:

    <CodeGroup>
      ```curl curl theme={null}
      curl --request GET \
      --url "https://api.brandfetch.io/v2/search/:name?c=BRANDFETCH_CLIENT_ID"
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Hotlinking">
    **We require Brand Search API to be directly embedded in your user-facing applications.**

    The API should be used directly as is, with all data fetched live and not altered or persisted. Your users should make requests to the API directly from their browsers.

    <b>The logo image URLs provided by the Brand Search API must be hotlinked</b>. Other data, such as brand names, should not be cached and should be used exclusively for building an autocomplete experience. Image URLs expire after 24 hours and must be refetched.

    For more information on the API’s availability, see our [uptime status](https://status.brandfetch.io/). We can provide custom SLAs for enterprise customers.

    If your use case requires more flexibility, please [contact us](https://brandfetch.com/developers/contact/sales) for a custom setup.
  </Accordion>

  <Accordion title="Replicating Brandfetch">
    **You cannot replicate the core user experience of Brandfetch.**

    The best way to ensure that your application doesn’t violate this guideline is by integrating Brandfetch into an existing app that offers more value than just the Brandfetch integration.

    Some examples:

    * ✅ The [Pitch integration](https://brandfetch.com/developers/customers/pitch) helps their users autocomplete brand names to streamline logo search within Pitch’s editor. Without this integration, the app still has a lot of value to its users.

    * 🚫 An unofficial Brand Search API that allows users to autocomplete brands. Without the API, the app has no content and no value to users.

    If you're unsure about your use case, please [contact us](https://brandfetch.com/developers/contact).
  </Accordion>
</AccordionGroup>

## Rate limits

Every plan includes a monthly Brand Search allowance: <b>500,000 requests per month</b> on the free plan, and 1 to 5 million on paid plans. See the [pricing page](https://brandfetch.com/developers/pricing). These are soft limits, so exceeding yours does not block you straight away. Traffic that runs far beyond your allowance can eventually be refused with a `429` carrying [`quota_exceeded`](#errors).

Usage is counted per client ID. Every `GET` answered with a `2xx` or `3xx` status counts, whether it was served from the edge cache or freshly. Browser preflight requests, refused requests, and requests without a valid client ID do not count. Your month's usage and every counted request are under **Usage History** in your [developer dashboard](https://developers.brandfetch.com).

To maintain platform reliability, two request throughput limits also apply:

* 200 requests every 5 minutes per IP address
* 6,000 requests every 5 minutes per client ID, counted across every address it is used from. Enterprise client IDs are exempt.

Both count answers served from the edge cache. The per-IP limit also counts browser preflight requests; the per-client limit leaves them out, so a browser that goes over it still receives a refusal it can read. The per-IP limit allows roughly 30 search sessions in a 5-minute period for a single visitor; the per-client limit applies to all of your application's traffic together. Use a [debounce strategy](https://developer.mozilla.org/en-US/docs/Glossary/Debounce) between keystrokes to stay under both. Exceeding the per-IP limit returns an HTTP `429` status code without an `x-bf-error` header; exceeding the per-client limit returns a `429` with `x-bf-error: rate_limited`. See [Errors](#errors) for how to tell a throughput block from the other reasons a request can be refused.

For enterprises, we provide custom solutions, including SLA agreements, custom terms, and flexible caching options to ensure optimal performance at scale. These plans are tailored to meet the needs of high-volume users.

Feel free to [contact us](https://brandfetch.com/developers/contact/sales) to discuss the right plan for your use case.

## Errors

When the Brand Search API refuses a request because of its client ID, its client ID's throughput or your allowance, the response carries an `x-bf-error` header naming the exact reason, and a JSON body with the same code in `error`, a `message` written for a human, and a `docs` link. The header is exposed through CORS, so a browser caller can read either one.

<Note>
  The per-IP throughput limit under [rate limits](#rate-limits) is enforced separately, before the client ID is looked at, so those `429` responses carry no `x-bf-error` header and no `error` field, only a short `message`. The presence of the header is what tells you the request was refused for one of the reasons below.
</Note>

| `x-bf-error` | Status | What happened | What to do |
| - | - | - | - |
| `quota_exceeded` | `429` | Your organization has searched far beyond its monthly Brand Search allowance. | Raise your allowance and the block lifts within seconds. It also lifts on its own when your next billing period starts. |
| `rate_limited` | `429` | Requests made with this client ID, by all of your users together, went over 6,000 in the last 5 minutes. | Debounce keystrokes and avoid sending the same search twice. The block lifts on its own once the rate over the last 5 minutes falls back under the limit. [Contact us](https://brandfetch.com/developers/contact) if your application needs more. |
| `client_id_invalid_signature` | `403` | The `?c=` client ID is present but doesn't verify. This is almost always a transcription error. | Copy the client ID from your [developer dashboard](https://developers.brandfetch.com) instead of reading it off a screenshot. The message names the characters that get confused most often: lowercase `l` against capital `I` and the digit `1`, and the digit `0` against capital `O`. |
| `client_id_required` | `403` | The request carried no `?c=` client ID. | Add `?c=YOUR_CLIENT_ID` to the URL. |
| `client_id_expired` | `410` | The client ID carries an expiry that has passed. | Use a client ID from your [developer dashboard](https://developers.brandfetch.com). |

### When a search fails

A search that could not be answered returns `503` with `x-bf-error: temporarily_unavailable` and a JSON body with a `message`. It never returns an empty array, so a `200` with `[]` always means no brand matched.

Retry after about 10 seconds. An identical request made sooner can get the same `503`. A `503` does not count towards your Brand Search allowance.

### Responses without an `x-bf-error` header

Every other response is either the per-IP throughput limit, which is checked before the client ID, or the search's own answer.

| Status | When | What you get |
| - | - | - |
| `200` | The search ran. | A JSON array of matching brands, possibly empty. |
| `400` | A query parameter is unknown, or `limit` is above 5. | A JSON body describing the invalid parameter. |
| `429` | The per-IP throughput limit was exceeded before the request reached the checks above. | A short JSON body. Slow down and retry after the window. |

<Tip>
  You can see all of these responses for your own traffic under **Usage History** in your [developer dashboard](https://developers.brandfetch.com), filtered by status class.
</Tip>

## API Reference

For more details, refer to our [API Reference](/reference/brand-search-api).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.