Is it the right API for you? Compare the interactive and the non-interactive API.
https://
URLs.
Invoke the service by accessing https://realfavicongenerator.net/api/favicon
with a POST method and a JSON document, documented below.
The response to this request is similar to the non-interactive API request response.
An example of the JSON document to post:
{ "favicon_generation": { "api_key": "87d5cd739b05c00416c4a19cd14a8bb5632ea563", "master_picture": { "type": "url", "url": "http://somesite.com/some_pic.png" }, "files_location": { "type": "path", "path": "/path/to/icons" }, "favicon_design": { "desktop_browser": {}, "ios": { "picture_aspect": "background_and_margin", "margin": "4", "background_color": "#123456", "startup_image": { "master_picture": { "type": "url", "url": "http://example.com/pic_for_ios_startup.png" }, "background_color": "#654321" }, "assets": { "ios6_and_prior_icons": false, "ios7_and_later_icons": true, "precomposed_icons": false, "declare_only_default_icon": true } }, "windows": { "picture_aspect": "white_silhouette", "background_color": "#654321", "assets": { "windows_80_ie_10_tile": true, "windows_10_ie_11_edge_tiles": { "small": false, "medium": true, "big": true, "rectangle": false } } }, "firefox_app": { "picture_aspect": "circle", "keep_picture_in_circle": "true", "circle_inner_margin": "5", "background_color": "#456789", "manifest": { "app_name": "My sample app", "app_description": "Yet another sample application", "developer_name": "Philippe Bernard", "developer_url": "http://stackoverflow.com/users/499917/philippe-b" } }, "android_chrome": { "picture_aspect": "shadow", "manifest": { "name": "My sample app", "display": "standalone", "orientation": "portrait", "start_url": "/homepage.html", "existing_manifest": "{\"name\": \"Yet another app\"}" }, "assets": { "legacy_icon": true, "low_resolution_icons": false }, "theme_color": "#4972ab" }, "safari_pinned_tab": { "picture_aspect": "black_and_white", "threshold": 60, "theme_color": "#136497" }, "coast": { "picture_aspect": "background_and_margin", "background_color": "#136497", "margin": "12%" }, "open_graph": { "picture_aspect": "background_and_margin", "background_color": "#136497", "margin": "12%", "ratio": "1.91:1" }, "yandex_browser": { "background_color": "background_color", "manifest": { "show_title": true, "version": "1.0" } } }, "settings": { "compression": "3", "scaling_algorithm": "Mitchell", "error_on_image_too_small": true, "readme_file": true, "html_code_file": false, "use_path_as_is": false }, "versioning": { "param_name": "ver", "param_value": "15Zd8" } } }
api_key
Your API key. No key yet? Register it now.
master_picture
type
Indicate how the master picture (used to generate the various favicon pictures) is transmitted to RealFaviconGenerator. Possible values are:
url
url
parameter with the URL of the picture. For example:
... "type": "url", "url": "http://some-site-that-host-the-pic.net/the_pic.png", ...
inline
content
parameter with the content of the picture, encoded in Base64. For example:
... "type": "inline", "content": "TWFuIGlz...bGVhc3VyZS4=", ...
A master picture can also be declared for each platform. For example, if a specific icon was designed for iOS:
... "ios": { "master_picture": { "type": "url", "url": "http://somesite.com/some_pic.png" }, "picture_aspect": "no_change" }, ...
files_location
type
Indicate how the user should select where the favicon files will go: at the root of the web site or in another directory. Possible values are:
root
path
path
parameter. For example:
... "type": "path", "path": "/path/to/icons", ...
favicon_design
These values reflect the various choices offered when you generate a favicon manually. If one of the following section is not present, the corresponding icons are not generated.
For example, if the ios
section is absent, there is no icon for iOS.
desktop_browser
ios
picture_aspect
no_change
background_and_margin
margin
and background_color
.margin
The margin to apply to the master picture to produce the Apple Touch icon.
The margin is set in pixels, for a 57x57 picture. So 3
will generate a 3 pixels margin for a 57x57 icon
and 9 pixels for a 180x180 icon. It can also be a percentage, such as 5%
.
background_color
The background color applied as the background of the Apple Touch icon.
startup_image
This section lets you define a startup image for iOS. If it is not present, no startup image is created.
Use background_and_margin
to declare a background color. If none is specified,
the background_and_margin
of the iOS Touch icon will be used. Warning:
if no background color was defined at all, the API will generate a startup image with transparent margins.
iOS prevents this and will fill the transparent regions with black.
You can also override the picture used to created the startup image with a master_picture
declaration.
app_name
The app name. When defined, this value is used by Safari as the default home screen caption (instead of the page title).
assets
One icon is enough to support all iOS devices. However, it is sometimes
useful to have more than one. Whatever the chosen options, at least one
icon is created and declared in the HTML. If you don't want iOS support at
all, just discard the whole ios
section.
ios6_and_prior_icons
Generate icons for iOS 6 and prior.
ios7_and_later_icons
Generate icons for iOS 7 and later.
precomposed_icons
Generate precomposed icons, in addition to regular icons.
declare_only_default_icon
If true
, only the default icon are declared in the HTML.
Else, all regular (ie. non-precompued) icons are declared.
windows
picture_aspect
no_change
white_silhouette
background_color
The background color to apply to the tile.
assets
By default, 5 icons are generated: 4 for Windows 8.1 and 11 (running IE 11 or Edge) and 1 for Windows 8.0 (running IE 10). The icons can be enabled or disabled one by one:
windows_80_ie_10_tile
windows_10_ie_11_edge_tiles > small
windows_10_ie_11_edge_tiles > medium
windows_10_ie_11_edge_tiles > big
windows_10_ie_11_edge_tiles > rectangle
existing_manifest
If there is an existing browserconfig.xml
file, RealFaviconGenerator can update it instead of creating a new one.
If so, pass it with the existing_manifest
attribute.
Make sure to JSON-encode this XML document to avoid any JSON syntax error.
Use on_conflict
to indicate how to react in case of conflict.
If the existing manifest contains an entry that RealFaviconGenerator also generates:
raise_error
: An error is raised and the API call fails.override
: The original value is replaced by the new one.keep_existing
: The original value is kept and the new one is ignored.error_on_override
is still supported but deprecated.
app_name
The app name. When defined, this value is used by IE as the default home screen caption (instead of the page title).
firefox_app
Define a manifest and icons for Firefox OS. Some of the following parameters are injected in the generated manifest. When a value is missing, the corresponding manifest field is filled with "TODO".
picture_aspect
no_change
circle
background_color
: Circle background color.margin
: Margin to apply to the master picture. Given in pixels, for a 60x60 icon. Or a percentage.keep_picture_in_circle
: If true
, the master picture is cropped in order to fit the circle.
Else, the master picture may extend beyond the circle.circle_inner_margin
: If keep_picture_in_circle
is
set to true
, this is the margin applied to the cropping of the master picture.overlay
: If true
, add the overlay.rounded_square
margin
and background_color
parameters.square
margin
and background_color
parameters.manifest
app_name
The application name.
app_description
A description of the application.
developer_name
The developer name.
developer_url
The Url of the developer personal web site.
existing_manifest
If there is an existing manifest file, RealFaviconGenerator can update it instead of creating a new one.
If so, pass it with the existing_manifest
attribute.
Make sure to value this attribute with an encoded version of this JSON document: it must appear as a regular string.
Use on_conflict
to indicate how to react in case of conflict.
If the existing manifest contains an entry that RealFaviconGenerator also generates:
raise_error
: An error is raised and the API call fails.override
: The original value is replaced by the new one.keep_existing
: The original value is kept and the new one is ignored.error_on_override
is still supported but deprecated.
android_chrome
Android Chrome M39 introduces a manifest file with corresponding icons.
The manifest and icons are generated only if the android_chrome
section is present.
picture_aspect
no_change
background_and_margin
margin
and
background_color
parameters.shadow
manifest
This section describes the manifest. It is mandatory.
name
The application name is used as the title of the link when the visitor adds the site to the home screen. This field is mandatory. There is no way to force Android Chrome to use the current page title.
start_url
The page actually added to the home screen. Typically, the home page of the site. Leave this field blank to let a visitor add any page to the home screen.
display
Specify the appearance of the web site when the user clicks the home scren link:
browser
browser
attribute, the display
attribute
is completely absent of the generated manifest.standalone
orientation
When present and display
is standalone
,
force the screen to a particular orientation. Either portrait
or
landscape
.
theme_color
The color applied to the standalone app when using the task switcher. Introduced in Android 5 Lollipop.
existing_manifest
If there is an existing manifest file, RealFaviconGenerator can update it instead of creating a new one.
If so, pass it with the existing_manifest
attribute.
Make sure to value this attribute with an encoded version of this JSON document: it must appear as a regular string.
Use on_conflict
to indicate how to react in case of conflict.
If the existing manifest contains an entry that RealFaviconGenerator also generates:
raise_error
: An error is raised and the API call fails.override
: The original value is replaced by the new one.keep_existing
: The original value is kept and the new one is ignored.error_on_override
is still supported but deprecated.
If there is an existing manifest, maybe it is already
declared in the HTML of the site. In that case, set
declared
to
false
to disable its declaration in the generated markups.
assets
legacy_icon
If true
, the service generates icons and HTML markups for
Android Chrome running on Android Chrome M38 and prior.
low_resolution_icons
If true
, the service creates all documented icons for
home screen
and splash screen.
Else, it creates only recommended, high resolution icons.
safari_pinned_tab
The pinned tab for Safari comes with version 9 and Mac OS X El Capitan. This is an SVG image with no background (ie. transparent) where paths must be black.
This icon is generated only if the safari_pinned_tab
section is present.
picture_aspect
no_change
silhouette
black_and_white
threshold
option (from 0
to 100
) to indicate
how colors should be turned to black or white.
Since the master picture is often a PNG, it is converted to SVG.theme_color
The theme color. Usually the dominant color of the master picture.
coast
Coast by Opera is a popular alternative on iOS.
Its icon is generated only if the coast
section is present.
Warning! At the time of writing, Coast does not select the 228x228 picture defined in its specifications. However, the next release of Coast will fix this. Therefore, unless you really want this icon now or if this documentation is not updated in time to reflect the availability of the fix, you should not not this option.
picture_aspect
no_change
background_and_margin
margin
and
background_color
parameters.open_graph
The Open Graph pictures is used by several services to illustrate a web page.
In particular, Facebook use this picture when a page is shared.
Although Open Graph picture is not a "favicon", it might be useful to generate it here.
The picture is generated only if the open_graph
section is present.
picture_aspect
no_change
background_and_margin
margin
,
background_color
and
ratio
parameters.
ratio
can be valued with square
or 1.91:1
.site_url
site_url
is the URL of the site, without path information
(eg. http://example.com/
but not http://example.com/path/to/icons
).
yandex_browser
Yandex Browser offers a "Tableau" page, similar to the Speed Dial or Opera. This browser is mostly used in Russia.
The manifest and icons are generated only if the yandex_browser
section is present.
background_color
The background applied by Yandex Browser to the icon.
manifest
This section describes the manifest. It is optional.
show_title
Display the title of the page in the bookmark. Default to true
.
version
The manifest version. Default to 1.0
.
existing_manifest
If there is an existing manifest file, RealFaviconGenerator can update it instead of creating a new one.
If so, pass it with the existing_manifest
attribute.
Make sure to value this attribute with an encoded version of this JSON document: it must appear as a regular string.
Use error_on_override
to indicate how to react in case of conflict.
If the existing manifest contains an entry that RealFaviconGenerator also generates:
true
: An error is raised.false
: The original value is replaced by the new one.settings
compression
Set the compression level, from 0
(no compression) to 5
(highest compression level).
scaling_algorithm
Set the scaling algorithm. Possible values:
Mitchell
NearestNeighbor
Cubic
Bilinear
Lanczos
Spline
error_on_image_too_small
When the master picture is too small for a particular, requested platform, nothing is generated for that platform.
For example, if the request contains a coast
section,
the master picture should be at least 228x to produce
the Coast icon. If the picture is smaller, the outcome of the request depends on error_on_image_too_small
:
true
: An error is raised and the whole request fails.false
: No error. The Coast icon is simply absent of the generated package.readme_file
If set to true
, generate
README.md
, which summarizes the
package manual installation steps.
html_code_file
If set to true
, generate
html_code.html
, which contains the
icons HTML markups. This file can be inlined as is in HTML pages.
use_path_as_is
This parameter is related with Issue#270.
Usually, the client tells where the icons are going to be hosted (eg. root directory of the web site) and expects RealFaviconGenerator to compute the HTML and various files (Web App Manifest, etc.) accordingly.
However, there are situations where the client has a particular requirement, which is to find the path everywhere it can appear. For example, the plugin for Ruby on Rails wants to post-process RealFaviconGenerator assets to make these resources part of the RoR asset pipeline.
This conflicts with the Web App Manifest, which use paths relative to the
images it references. When the icon path is relative
(eg. sub/dir
), the Web App Manifest is not supposed to use this
path (eg. some-icon.png
, and not
sub/dir/some-icon.png
).
This used to be an issue in
RealFaviconGenerator, and some API clients relied on it.
The use_path_as_is
parameter
was introduced to deal with this situation.
Its behavior:
false
:
Let RealFaviconGenerator compute the paths in order to get a working package.
For example,
Wep App Manifest and Browser configuration have different policies,
and RealFaviconGenerator takes this into account. This is the behavior you
expect when creating your favicon by visiting RealFaviconGenerator web site.
true
:
Force RealFaviconGenerator to insert the path everywhere. This option
makes sense only when expecting to post-process the generated assets.
For example, you can pass DummyPathReplaceIt12456
as the path
and set use_path_as_is
to
true
. Then, when the API returns the package, search/replace
this particular string with something useful, like templating content.
In order to preserve backward compatibility,
use_path_as_is
defaults to
true
, even if the opposite would have been more logical.
If you are working on a client that do not need to post-process the favicon
package, you should explicitely set this parameter to false
.
If you don't, you face the
issue#270 as if it was not fixed.
versioning
When a browser loads a favicon for the first time, it tends to cache it and to never load it again. When your web site is not new and you want to update your favicon, that can be a problem: your loyal visitors won't notice the change. A workaround is to append a version to the favicon URLs as a query parameter. This setion lets you do just that.
When this section is absent of set to false
(ie. versioning: false
),
the favicon files are not versioned.
When this section is set to true
(ie. versioning: true
),
versioning is generated. The query parameter name is v
and the value is a hashed timestamp.
These two values can be overriden with param_name
and
param_value
.
New platforms appear constaly or are updated. RealFaviconGenerator evolves to be as up-to-date as possible. It is also updated to fix issues. These changes are listed in the change log. When using the API, it can be useful to access the change log programmatically in order to answer this basic question: was RealFaviconGenerator updated since the favicon was generated for the last time?
For example, suppose the API is used in May to generate a favicon. In June, a major change happens in RealFaviconGenerator: it is updated for the latest version of iOS. By asking RealFaviconGenerator for changes, you can discover this change and suggest your users to generate their favicons again.
Retrieve the changes by issuing a GET to https://realfavicongenerator.net/api/versions
.
This entry point takes an optional parameter, since
. This parameter must be an existing version.
Usually, this parameter is populated with the version
field returned by a favicon generation performed some time ago.
For example, https://realfavicongenerator.net/api/versions?since=0.5
returns something like:
[ { "version": "0.6", "date": "2014/02/11", "description": "(some human readable, HTML formatted message here)", "importance": "Minor", "update_or_not": "(some human readable, HTML formatted message here)", "relevance": { "automated_update": true, "manual_update": false } }, { "version": "0.7", "date": "2014/04/16", "description": "(some human readable, HTML formatted message here)", "importance": "Minor", "update_or_not": "(some human readable, HTML formatted message here)", "relevance": { "automated_update": true, "manual_update": true } } ]
As a side effect, getting an empty document (ie. no element in the JSON array) means no change in RealFaviconGenerator since the last favicon generation.
Each update comes with a relevance
section and two boolean attributes:
automated_update
manual_update
To understand these attributes, let's consider three fictive updates:
automated_update
is true
because running an existing non-interactive API request does take advantage of this update. But manual_update
is false
because
a human intervention does not add any benefit.manual_update
is true
because human intervention makes sense: a user can take design decision about this new platform, etc.
Same for the non-interactive API: a developer can edit an existing request to generate stuff for this new platform.
automated_update
is false
because running an existing non-ineractive API request as is does not add any value:
it would generate the exact same set of icons and HTML code as before.
automated_update
and manual_update
are set to true
.
In addition, the classic change log page also supports since
.
For example, https://realfavicongenerator.net/change_log?since=0.5
lists changes after version 0.5. You can build such URL to redirect your users whenever an update is available.