How to use

Favatar can be used by sending requests to the following URL:

http://favatar.mention.com/image?format=image&api_key=your_key&url=http://www.mention.com/

Parameters

Return value (image format)

When an icon has been found, the API returns the content of the image in the response body, with a proper content type.

When no icon has been found, the API returns either a 404 response, or a 301 redirection to the URL provided in the default parameter.

Return value (json format)

When an icon has been found, the following JSON hash is returned:

{
     "url": // URL of the icon
     "mimeType": // The mime type
     "data": // The icon, encoded in base64
}

If no icon can be found for a URL, null is returned.

If the callback parameter is provided, the API will reply in JSONP format, with additional wrapping:

callback({
     "statusCode": // The HTTP status code that would have been sent in a non-jsonp request
     "body": // The response that would have been sent in a non-jsonp request (e.g. a json hash)
})

A data url can be formed with the mime type and the base64 data:

"data:" + mimeType + ";base64," + data

jQuery example

var params = {
     url: 'http://www.example.com/',
     api_key: 'your_key',
     format: 'json',
};
                        
$.getJSON('http://favatar.mention.com/image?callback=?', params, function(result) {
    // use result here
});

Icon types

A website can declare its icons in multiple ways.

When multiple icons are found, the first one is returned, by order of preference:

Special URLs

For most URLs, Favatar returns the icon for the URL's root path (e.g. for http://www.example.com/some/path, the icon for http://www.example.com/ is returned).

Some URLs are treated specifically:

Try it

mention