Logos in your pages
https://img.hydrafetch.com/logo/{domain} returns the company’s logo as an image, not as JSON. It comes from the same work behind brand data, cut down to the one thing most people want.
Logo images never use credits
They count against a separate allowance in your plan. A page showing forty logos uses forty logo serves and zero credits.
The key goes in your page
An
<img> tag cannot send a header, so this endpoint takes a publishable key in the URL. Publishable keys are meant to be public, and they work here and nowhere else.Publishable keys
Create one in the dashboard next to your secret keys. They start withhf_pk_, and it is safe to commit them and put them in browser HTML.
A publishable key cannot call /v1/web/scrape, /v1/web/crawl or any other endpoint; those answer 401. It only serves logos, which is why it is safe to publish.
You can lock a key to a list of domains. Requests are then checked against their Referer or Origin header, and anything else is refused.
If you lock a key, make sure your pages send a referrer. A Referrer-Policy of no-referrer, or <img referrerpolicy="no-referrer">, gets every request refused.
Options
The longest side in pixels, from 16 to 512. Rounded up to the nearest size we store.
The background you are drawing on:
light, dark or auto. light and dark fix the logo to one colour. auto follows the viewer’s operating system setting. Read Getting the theme right before using auto.icon for the square mark, wordmark for the full logo with the name. If the company has only one, you get that one.What to serve when we have no logo:
monogram (the first letter in the brand’s colour), transparent (a 1 by 1 clear pixel) or 404.Examples
Dark background
The full wordmark
Remove the image when there is no logo
Getting the theme right
Most logos are one colour, and the wrong one is invisible, not just wrong. A white logo on a white card looks to your users as if there is no logo at all. Pass the theme your page is actually showing, not the operating system’s:theme=auto only in one case. An adaptive logo decides its colour inside the image, and an image in an <img> tag cannot see your page, only the viewer’s operating system setting. If your site always follows the operating system, auto is right. If your site has its own light and dark switch, auto is wrong whenever a visitor sets your switch differently from their system, which is exactly when a missing logo is most noticeable.
So with a theme switch, pass light or dark yourself. The React package takes the theme once on its provider and every <Logo> inside follows it:
A domain we have never seen
The first request for a new domain looks it up there and then and waits, instead of answering with a placeholder. A placeholder on the first view would look like “they have no logo” when we are seconds away from having one. The wait has a limit. Past it, the lookup finishes in the background, that one request gets the fallback, and the next request is served from storage. Expect a new domain to take a few seconds the first time and every request after to be instant.Caching
A logo is served withCache-Control: public, max-age=86400, so browsers and CDNs keep it for a day. Fallbacks are cached for much less time, so a domain we resolve later starts showing its real logo on its own.
Because logos are cached at the edge, most requests never reach us, and anything served from cache uses none of your allowance.
A logo as data
From your server,GET /v1/web/brand/logo returns the logo’s details as JSON, including a public image URL you can store and show anywhere. It costs 1 credit, compared with 5 for the full brand record.
domain (a URL works too), theme and type, with the same meanings as above.
Billing
Logo images count against your plan’s logo allowance for each billing cycle, separately from credits. A logo image never uses a credit, and credits never buy logo images. Only a delivered logo counts. If we have no logo, or are still looking it up, you get a placeholder and your allowance is not touched. Neither is anything served from the edge cache. Going over your allowance does not break your pages straight away. For 7 days we keep answering with monogram placeholders instead of errors, so nothing on your site turns into a broken image while you notice and upgrade. After that the endpoint returns an error. See Plans and billing.Related
Brand data
The full record: logos, colours, fonts and socials.
API keys
Creating publishable and secret keys, and what to do if one leaks.
SDKs
Including the browser and React logo packages.
Errors
What a 401, 403 or 429 means.