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`

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`

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.