Favicon Generator
  • Favicon
    • Favicon generator
    • SVG Favicon
    • Favicon checker
    • Favicon generator for Gulp
    • Favicon generator for Grunt
    • Favicon generator for Ruby on Rails
    • Favicon generator for Node.js CLI
    • Favicon generator for ASP.NET Core
    • Favicon generator for Google Web Starter Kit
  • Social
    • Social generator
    • Social checker
  • API
    • API introduction
    • Favicon generation interactive API
    • Favicon generation non-interactive API
    • Download the favicon of a website
    • Favicon analysis
    • Web components
  • Contribute
    • Report an issue
    • Compatibility test
    • Donate
  • Misc
    • FAQ
    • Change log
    • Compatibility
    • Extensions
    • Blog
    • Contact us
    • Newsletter
    • Terms of service
    • Privacy policy
    • Cookies

Non-interactive API

Is it the right API for you? Compare the interactive and the non-interactive API.

RealFaviconGenerator will switch to always-on SSL on February 15th 2016. Make sure to use https:// URLs.

Generate favicon

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
There is a master picture to transmit, passed by URL. When the user will be presented the RealFaviconGenerator interface, the picture will be already loaded and he won't have to select it on his PC. When using this choice, you should also set the 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
There is a master picture to transmit, inlined in the JSON document. When the user will be presented the RealFaviconGenerator interface, the picture will be already loaded and he won't have to select it on his PC. When using this choice, you should also set the 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
The favicon files are expected to be placed in the root directory of the web site. The user will not have the opportunity to select it in the RealFaviconGenerator interface.
path
The favicon files are expected to be placed in a specific directory of the web site. The user will not have the opportunity to select it in the RealFaviconGenerator interface. When using this value, you should also set the 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

Design for the classic desktop browsers. This section has no parameters. The philosophy behind is that the master picture is usually designed for this purpose.

ios

picture_aspect
no_change
Use the master picture as is.
background_and_margin
Apply a background and a margin to the master picture. When using this value, also specify 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
Use the master picture as is.
white_silhouette
Turn the master picture into a 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.
The old parameter 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
Use the master picture as is.
circle
Generate a circular icon. This is the primary icon format used in Firefox OS. This value comes with the following parameters:
  • 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
Generate a square icon with rounded corners. Although no builtin app is using this fomat, it is documented in the Firefox OS guidelines. Combine this value with the margin and background_color parameters.
square
Generate a square icon. Although no builtin app is using this fomat, it is documented in the Firefox OS guidelines. Combine this value with the 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.
The old parameter 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
Use the master picture as is.
background_and_margin
Generate a square icon with margin and background. Combine this value with the margin and background_color parameters.
shadow
Add a small drop shadow to the master picture. This effect is used by several Google apps, such as Chrome, Gmail, Drive or Inbox.
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
The site is opened like any regular bookmark, in a new Chrome tab. Because Android Chrome does not actually support the browser attribute, the display attribute is completely absent of the generated manifest.
standalone
The web site is somehow treated like a native application. When the home screen link is clicked, a new Chrome instance is opened, the navigation UI is not displayed and the web site is displayed full-screen.
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.
The old parameter 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
Use the master picture as is. Since this image must be in SVG format, so must be the master picture if this option is chosen.
silhouette
Turn the master picture as a silhouette: transparent regions remain transparent and the opaque regions become black. Since the master picture is often a PNG, it is converted to SVG.
black_and_white
Turn the master picture into a black-and-white pictures. Use the 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
Use the master picture as is.
background_and_margin
Generate a square icon with margin and background. Combine this value with the 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
Use the master picture as is.
background_and_margin
Generate a square icon with margin and background. Combine this value with the 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.

Change log / Check for updates

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
Indicate if it makes sense to apply the update autmatically (ie. by running an existing non-interactive API request).
manual_update
Indicate if it makes sense to apply the update manually (ie. by prompting a human to visit RFG to generate the favion again or to edit an existing non-interactive API request).

To understand these attributes, let's consider three fictive updates:

  • Update A: RFG now generates lighter icons. There is no visible change anywhere: the favicon editor remains the same, no new setting for the user to click. The non-interactive API is also unchanged. It's just that RFG creates 10% lighter pictures. In this example, 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.
  • Update B: RFG now supports a new platform. There is a new section in the favicon editor and the non-interactive API was augmented accordingly. Here, 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.
  • Update C: updates A and B combined. RFG supports a new platform and all generated icons are 10% lighter. Here, both 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.

Favicon Generator
Favicon Checker
Favicon for Gulp
Favicon for Grunt
Favicon for Ruby on Rails
Favicon for Node.js CLI
Favicon for ASP.NET Core
Favicon for Google Web Starter Kit
FAQ
Blog
Report bug
Change Log
Compatibility
Extensions
API
Compatibility Test
Contact us
Donate
Newsletter
Terms of service
Privacy policy
Cookies
RealFaviconGenerator.net © 2013-2022