microlinkhq / unavatar

Get unified user avatar from social networks, including Instagram, SoundCloud, Telegram, Twitter, YouTube & more.

Welcome to unavatar.io, the ultimate avatar service that offers everything you need to easily retrieve user avatars:

• Versatile: A wide range of platforms and services including Facebook, Instagram, YouTube, Twitter, Gravatar, etc., meaning you can rule all of them just querying against unavatar.

• Speed: Designed to be fast and efficient, all requests are being cached and delivered +200 global datacenters, allowing you to consume avatars instantly, counting more than 20 millions requests per month.

• Optimize: All the images are not only compressed on-the-fly to reduce their size and save bandwith, but also optimized to maintain a high-quality ratio. They are ready for immediate use, enhancing the overall optimization of your website or application.

• Integration: The service seamlessly incorporates into your current applications or websites with ease. We offer straightforward documentation and comprehensive support to ensure a quick and effortless onboarding experience.

In summary, unavatar.io provides versatility, speed, optimization, and effortless integration, making it the ultimate avatar retrieval service.

Quick start

The service is a single endpoint exposed in unavatar.io that can resolve:

• an email: https://unavatar.io/[email protected]
• an username: https://unavatar.io/kikobeats
• a domain: https://unavatar.io/reddit.com

So, no matter what type of query you use, unavatar.io has you covered. You can read more about that in providers.

Query parameters

TTL

Type: number|string
Default: '24h'
Range: from '1h' to '28d'

It determines the maximum quantity of time an avatar is considered fresh.

e.g., https://unavatar.io/kikobeats?ttl=1h

When you look up for a user avatar for the very first time, the service will determine it and cache it respecting TTL value.

The same resource will continue to be used until reach TTL expiration. After that, the resource will be computed, and cache as fresh, starting the cycle.

Fallback

Type: string|boolean

When it can't be possible to get a user avatar, a fallback image is returned instead, and it can be personalized to fit better with your website or application style.

You can get one from boringavatars.com:

e.g., https://unavatar.io/github/37t?fallback=https://source.boringavatars.com/marble/120/1337_user?colors=264653r,2a9d8f,e9c46a,f4a261,e76f51

or avatar.vercel.sh:

e.g., https://unavatar.io/github/37t?fallback=https://avatar.vercel.sh/37t?size=400

or even an static image:

e.g., https://unavatar.io/github/37t?fallback=https://avatars.githubusercontent.com/u/66378906?v=4

You can pass fallback=false for explicitly disable this behavior. In that case, a 404 Not Found HTTP status code will returned when is not possible to get the user avatar.

JSON

The service returns media content by default.

This is in this way to make easier consume the service from HTML markup.

In case you want to get a JSON payload as response, just pass json=true:

e.g., https://unavatar.io/kikobeats?json

Limitations

For preventing abusive usage, the service has associated a daily rate limit based on requests IP address.

You can verify for your rate limit state checking the following headers in the response:

• x-rate-limit-limit: The maximum number of requests that the consumer is permitted to make per minute.
• x-rate-limit-remaining: The number of requests remaining in the current rate limit window.
• x-rate-limit-reset: The time at which the current rate limit window resets in UTC epoch seconds.

When you reach the API quota limit, you will experience HTTP 429 errors, meaning you need to wait until the API quota reset. If you need more quota, contact us.

Providers

With unavatar.io, you can retrieve user avatars based on an email, domain, or username.

The providers are grouped based on which kind of input they can resolve.

Based on that, a subset of providers will be used for resolving the user query, being the avatar resolved the fastest provider that resolve the query successfully.

Alternatively, you can query for an individual provider.

DeviantArt

Type: username

It resolves user avatar against deviantart.com.

e.g., https://unavatar.io/deviantart/spyed

Dribbble

Type: username

It resolves user avatar against dribbble.com.

e.g., https://unavatar.io/dribbble/omidnikrah

DuckDuckGo

Type: domain

It resolves user avatar using duckduckgo.com.

e.g., https://unavatar.io/duckduckgo/gummibeer.dev

GitHub

Type: username

It resolves user avatar against github.com.

e.g., https://unavatar.io/github/mdo

Google

Type: domain

It resolves user avatar using google.com.

e.g., https://unavatar.io/google/netflix.com

Gravatar

Type: email

It resolves user avatar against gravatar.com.

e.g., https://unavatar.io/gravatar/[email protected]

Instagram

Type: username

It resolves user avatar against instagram.com.

e.g., https://unavatar.io/instagram/willsmith

Microlink

Type: domain

It resolves user avatar using microlink.io.

e.g., https://unavatar.io/microlink/microlink.io

Read.cv

Type: username

It resolves user avatar against read.cv.

e.g., https://unavatar.io/readcv/elenatorro

Reddit

Type: username

It resolves user avatar against reddit.com.

e.g., https://unavatar.io/reddit/kikobeats

SoundCloud

Type: username

It resolves user avatar against soundcloud.com.

e.g., https://unavatar.io/soundcloud/gorillaz

Substack

Type: username

It resolves user avatar against substack.com.

e.g., https://unavatar.io/substack/bankless

Telegram

Type: username

It resolves user avatar against telegram.com.

e.g., https://unavatar.io/telegram/drsdavidsoft

Twitter

Type: username

It resolves user avatar against twitter.com.

e.g., https://unavatar.io/twitter/kikobeats

Twitch

Type: username

It resolves user avatar against twitch.tv.

e.g., https://unavatar.io/twitter/midudev

YouTube

Type: username

It resolves user avatar against youtube.com.

e.g., https://unavatar.io/youtube/casey

unavatar's Issues

Add GitLab support

demo url: https://gitlab.com/gitlab-bot

Add `discord` provider

Is there any way to get the avatar back on avatars.io?

I found this project via this blog, there is a project that used avatars.io (aka getchute) for avatar service in 2013-2015 years, now I have many hash values of the avatar.io (the url like avatars.io/13APvgixgc/?size=large) but I can't retrieve the previous avatar

Get Instagram full size avatar

Looking up by email return default tiktok image

Weird, issue, but it seems looking up via email is broken ?

poking any of those urls https://unavatar.io/[email protected], https://unavatar.io/[email protected] returns a default tiktok image, despite the latter having a correct gravatar (https://unavatar.io/gravatar/[email protected]).

However, using the example url (https://unavatar.io/[email protected]), returns a correct avatar.

Unsure how to diagnose this, tbh.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

Add `readcv` provider

Improve Twitter regex size extraction

live service seems down?

Currently all links like https://unavatar.io/[email protected] are 502 Bad Gateway (CloudFlare)

add `providers` query parameters

The service is offering:

• query against all the providers; or
• query against one provider

It could be nice to query against a subset of providers:

?providers=microlink,google,duckduckgo

Add your 👍 to see this implemented.

Ensure twitter endpoint is working well

All providers return the default avatar

Hey @Kikobeats 👋

I noticed that unavatar.io stopped working a couple of days ago (see https://unavatar.io/jack for example).

Running the service locally, I see the latest commit can't resolve most providers (they always return the default avatar). This is the commit where I see things start failing: b70fa08.

I tried debugging the problem but couldn't find the root cause yet.

Let me know if there is something I can do to help!

support multiple usernames / emails

Why

• I have usernames (or a guess of usernames) from multiple sources github, twitter, etc ... I want to pass them all to unavatar because I may not know which are real
• I have multiple emails for a user, unavatar may find some matches for some but not others

How

use comma separated list of names to find first match

<img src="https://unavatar.now.sh/:username1,:username2,:username3,email1,email2" />

Add `tiktok` provider

Incorrect image URL in the example

Improve Privacy

To avoid expose emails into the URL, gravatar encode it using MD5.

Take a look at the provider/gravatar.

The service can do that because the user is previously registered at gravatar portal.

In the case of unavatar, the service aims to be stateless without previous register or login.

Let determinate if we can do something in order to improve user privacy.

For example, we can support provide the url encoded base64. That's a reversible encoding and of course it doesn't securize your data, but at least it prevents be crawler for simple text scan bots.

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

Throttling issues for facebook avatars

Is there any restriction get retrieving the facebook avatars?

Out of 30 request, we get 20 times the facebook logo.

Is it might be the case that facebook is requesting for login?

Any theories?

some request cause unexpected behavior

I'm currently getting this error :/

Upgrade to `helmet` 5.0.0 has caused CORS issues

@Kikobeats PR #173 seems to have caused a CORS issue. We're seeing broken avatars on our products.

Originally posted by @jbrooksuk in #173 (comment)

Some domain avatars no longer rendering

I'm seeing avatars queried by domain no longer render where they previously were working fine.

Examples being:
https://unavatar.now.sh/qz.com
https://unavatar.now.sh/mail.bloombergbusiness.com

...where they return a 504 or just a generic image.

Add default avatar

Could be nice support default avatar fallback using an API parameter

tiktok default image in 404 case

Unavatar returns a tiktok image even if the user does not exist.

This is a problem with tiktok provider.

You are checking:

$('meta[property="og:image"]').attr('content')

on tiktok response. But this tag occurs with 404.

Examples:
https://www.tiktok.com/@invalid_user_i_think
https://unavatar.io/invalid_user_i_think?fallback=false -> returns tiktok image, should 404

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

Implement identicon

similar to

• https://github.com/dgraham/identicon (GitHub approach)
• https://github.com/tobiaslins/avatar (color + letters approach)
• https://joeschmoe.io/ (AMAISING)
• https://github.com/Gustu/string-to-color

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

Thank you

This is not an issue, but rather an opportunity to say thank you!

I am already using this on my blog: https://loige.co/speaking/ ❤️

Whats the default source for username query

Hey,

I would like to ask for default provider for quering image for username e.g https://unavatar.io/kikobeats

If its a twitter, then there is a problem for example - https://unavatar.io/twitter/MichalMzr . Its my profile https://twitter.com/MichalMzr
There is a probably bug in twitter profile provider, becouse its returning a empty image.

Uses project is calling a query by username and its returning a strange result - wesbos/awesome-uses#1625

DUPLICATE

As of 12/17 it seems the twitter route is failing to return an avatar for any username entered. It returns the default black smiley face instead.

Add Twitch provider

Hey Kiko, any chance to get Twitch provider as well? You rock!

Twitter not working

The sample twitter link: https://unavatar.now.sh/twitter/kikobeats doesn't work, nor do any requests I make!

EDIT: Seems like 'got' is getting a 400 error from Twitter, maybe they are blocking this type of request? I tried using 'request' package to scrape the HTML but it returns an incompatible browser page.

I've just decided to sign up for the Twitter API and create my own script to fetch the profile images. It's rate limited at 900 rq/15min so I don't know if that's a viable solution for this project.

gravatar wrong example

Last link

https://unavatar.now.sh/email/[email protected]

should be

https://unavatar.now.sh/gravatar/[email protected]

;)

An in-range update of cors is breaking the build 🚨

The dependency cors was updated from 2.8.4 to 2.8.5.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

cors is a direct dependency of this project, and it is very likely causing it to break. If other packages depend on yours, this update is probably also breaking those in turn.

Status Details

• ❌ continuous-integration/travis-ci/push: The Travis CI build could not complete due to an error (Details).

---

Commits

The new version differs by 52 commits.

• 9158a86 2.8.5
• 01477dc Fix setting "maxAge" option to 0
• cb91054 build: [email protected]
• c023f4f build: [email protected]
• 9daa37d build: [email protected]
• 697ea95 build: restructure Travis CI build steps
• 228b4ca build: [email protected]
• db046b2 build: [email protected]
• f45d533 tests: remove mocha.opts file
• 00d6eec build: use yaml eslint configuration
• 0168ac2 build: [email protected]
• 3af6d30 build: [email protected]
• b5bbc28 build: support Node.js 10.x
• 2685e66 docs: add note for rest tools / servers in dynamic origin example
• b42b8b3 docs: improve readability on if-else statement

There are 52 commits in total.

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

Add `linkedin` provider

Get avatar from YouTube

Fallback does not work if obtain the user avatar based on the input from email.

Fallback does not work if obtain the user avatar based on the input from email.
For example:
https://unavatar.now.sh/jgjhsdgfjsd?fallback=https://i.imgur.com/0d1TFfQ.jpg - works
https://unavatar.now.sh/jgjhs@dgfjsd?fallback=https://i.imgur.com/0d1TFfQ.jpg - not working, shows default avatar. Reason in @.

Instagram not working

possibly being blocked on now.sh instance

Use fallback avatar in case fallback URL is not reachable

For some reason I get a 500 error for the following url: https://unavatar.io/github/qmcclure?fallback=http%3A%2F%2F127.0.0.1%3A8000%2Fimages%2Flaravelio-icon-gray.svg

This is because I'm passing a development url for the fallback icon. I'm wondering if instead of the 500 error we could just show the default unavatar fallback?

revamp website

• https://zeit-style.vercel.app
• https://geist-ui.dev/en-us
• https://apex.sh/docs/up/

Images not loading - 524 error.

Hi, we utilise unavatar & have for sometime been using Gravatar as the last fallback on the end of the string, to display the Gravatar fallback image for users without a valid link on our site. This is seeded data, but shows the syntax we have been using:

https://unavatar.io/[email protected]?fallback=https://gravatar.com/avatar/019a7efaccba86d185277f7d9972cc79f9a9386c902b5de03b12c478d86f431d?s=300

Until about 24 hours ago loading the question mark fallback avatar that Gravatar uses worked, but it has since stopped working & is now giving a 524 response and if accessed directly via the browser a cloud flare error page.

Has there been any changes in the service?

I tried changing it to the gravatar provider as per the unavatar docs, with the following syntax:

https://unavatar.io/[email protected]?fallback=https://unavatar.io/gravatar/[email protected]

It resulted in the same thing, the 524 error.

It's effecting new signups & users changing links on their profile in production.

Would appreciate any advice.

Add a size option?

Love the service. So simple and easy to use!

Is there a way to set the maximum size of the image returned?

Thanks!

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because it uses your CI build statuses to figure out when to notify you about breaking changes.

Since we didn’t receive a CI status on the greenkeeper/initial branch, it’s possible that you don’t have CI set up yet. We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

If you have already set up a CI for this repository, you might need to check how it’s configured. Make sure it is set to run on all new branches. If you don’t want it to run on absolutely every branch, you can whitelist branches starting with greenkeeper/.

Once you have installed and configured CI on this repository correctly, you’ll need to re-trigger Greenkeeper’s initial pull request. To do this, please delete the greenkeeper/initial branch in this repository, and then remove and re-add this repository to the Greenkeeper App’s white list on Github. You'll find this list on your repo or organization’s settings page, under Installed GitHub Apps.

gravatar avatar not updating

I changed my Gravatar avatar and it is still not updating in Unavatar
This can be from the CDN cache system

Gravatar: disable default avatar

Unavatar's fallback does not work for email, because bad email addresses trigger Gravatar's fallback and get Gravatar's default image. For example, see the result of https://unavatar.now.sh/[email protected] - it is Gravatar's fallback image, not Unavatar's fallback.

Add `meetup` provider

Not sure if it's possible but doing live streaming for a group that is based with Meetup.com so being able to pull avatars fro there would be useful.

Implement a banner art fetching option

Currently one can only get the avatar, but another option be added to fetch the banner art of the profile. For example Twitter, the structure is practically the same to the profile picture so adding that functionality wouldn't be to hard.

Add domain logo extraction

Support pass an url for extracting logo

https://unavatar.sh/kikobeats.com

Any plans to support crypto wallets?

I'm thinking like using ETH wallets, and then either checking ENS or OpenSea for their avatar.

I've had to implement this functionality a few times in my own projects; and after I saw your post on ProductHunt I thought it would be perfect for that!

🙌 cheers! Great project.