Favicon Generator

Favicon API

Plugin or CMS developer? Integrate RealFaviconGenerator and offer an up-to-date favicon creation tool to your users.

In a nutshell

You develop a CMS or a plugin for a CMS, such as Drupal or WordPress. Your users manage the CMS with a web interface, made of core compopents and plugins. You want to offer a "Setup favicon" feature so your users can easily create a platform agnostic favicon for their web site or blog.

With the API, you can provide the following experience:

  • From the CMS web interface, the user triggers the "Create favicon" feature.
  • He is redirected to RealFaviconGenerator and is presented the classic favicon editor.
  • As soon as he clics the "Generate Favicon" button, he is redirected to the CMS.
  • The CMS receives the generated pictures and HTML code and install them automatically.

In addition, when invoking RealFaviconGenerator, the CMS/plugin has the possibility to submit two major parameters:

  • The master picture to use. Maybe the CMS already stores a high definition logo that can serve as the favicon model. No need for the user to submit it again.
  • The destination of the files. The CMS may have a dedicated location for the favicon files, such as /files/static/. In this case, the user should not have the opportunity to select the path manually, this should be handled in the background by the CMS and RealFaviconGenerator.

Demonstration and sample code

Checkout this online demo. When you are done, you can clone the demo project and get a taste of the API.

Register your key

As an API user, you need an API key, as usual. Type your email below to receive your key. You can also use this form to receive your key again if you forgot it. We will use your email address only for API-related news. We won't spam you, share your email or whatever.

Reference

Generate favicon

Invoke the service

Invoke the service by accessing http://realfavicongenerator.net/api/favicon_generator with a GET or a POST method. Pass a parameter named json_params, valued with a JSON document such as:
{
	"favicon_generation": {
		"api_key": "87d5cd739b05c00416c4a19cd14a8bb5632ea563",
		"master_picture": {
			"type": "url",
			"url": "http://somesite.com/some_pic.png",
			"demo": "false"
		},
		"files_location": {
			"type": "path",
			"path": "/path/to/icons"
		},
		"callback": {
			"type": "url",
			"url": "http://somesite.com/callback",
			"short_url": "false",
			"path_only": "false",
			"custom_parameter": "ref=157539001"
		}
	}
}
api_key

Your API key.

master_picture
type

Indicate how the master picture (used to generate the various favicon pictures) is transmitted to RealFaviconGenerator. Possible values are:

no_picture
There is no master picture to transmit. The user will pick one from RealFaviconGenerator. For example, you are writing a plugin for a CMS and you have no "natural" picture at hand that could be used as the master picture.
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=",
...
demo

If no master picture is submitted, the user has to upload one. When the demo parameter is set to true, a "Demo with this picture" button is displayed along with the "Select your favicon picture" button. By default, the demo button is hidden.

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:

no_location
There is no predefined location. The user will have the opportunity to select it in the RealFaviconGenerator interface.
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",
...
callback
type

Indicate the type of callback:

url
After the favicon generation, the user is redirected to a specific URL. This is the prefered mode, as it allows the caller to regain control and install the generated favicon. In this mode, you should also set the url parameter. Optionnaly, you can set a parameter that will be returned to the callback URL via custom_parameter:
"type": "url",
"url": "http://myownsite.com/rfg_calback",
"custom_parameter": "ref=19421384"
The callback URL will receive a JSON document as a parameter. Since this document can be a few hundred bytes long, this can cause troubles with some servers which do not accept long URLs. In this situation, the short_url parameter can be set to true. In addition, some platforms and hosting services reject URLs in the callback. To prevent this issue, the path_only parameter can be set to true to receive only a path. See the next section for more information.
none
After the favicon generation, the user has the opportunity to download the files directly from RealFaviconGenerator. The experience is the same as using RealFaviconGenerator directly, as a regular user. This mode is useful when the API is invoked from a non-Web environment, like a desktop application.

Regain control

Once the favicon edition is completed (or if an error occurs), the callback URL is invoked with a GET request, along with a JSON document as the value of the json_result parameter. For example:

{
	"favicon_generation_result": {
		"result": {
			"status": "success"
		},
		"favicon": {
			"package_url": "http://realfavicongenerator.net/files/0156213fd1232131.zip",
			"compression": "true"
			"html_code": "Html code here...",
		},
		"files_location": {
			"type": "path",
			"path": "/path/to/icons"
		},
		"preview_picture_url": "http://realfavicongenerator.net/files/0156213fd1232131/favicon_preview.png",
		"custom_parameter": "ref=157539001",
		"version": "0.9"
	}
}
result
Basicaly says if the invocation succeeded or not.
status
Indicate the status of the call.
success
The invocation was successful. Look for the other parameters to get the generated favicon.
error
An error occured. The error_message parameter to get a human-readable error message.
"result": {
	"status": "error",
	"error_message": "Invalid API key"
}
favicon

Container for the favicon itself: package (which contains the pictures and other files) and HTML code to insert in HTML pages.

package_url

The URL where the favicon package can be downloaded. This package is a zip file which contains the files to be deployed as is. The archive contains all files at its root.

Warning: since all files are automatically deleted after a few hours, this package must be downloaded soon after the invocation of the service. This URL should not be saved and used as a permalink.

compression
Indicates if the favicon pictures were compressed or not.
html_code
The HTML code to be inserted in every pages of the target site.
files_location

This section indicates where the favicon files should be stored. Note that the HTML code found in html_codereflects this location. Therefore, it is important to respect the istructions in files_location in order to make HTML code and favicon files match. Also note that this section reflects the equivalent section you (optionally) specified in the request. In other words, if, in the request, you asked the files to be placed in /path/to/icons, the response just reflects this.

type
root
The favicon files must be placed in the root directory of the web site.
path
The favicon files must be placed in a specific directory of the web site. In this case, read the content of path to find this path.
preview_picture_url

In addition to the favicon material itself, the service generates a preview picture. This picture can be presented to the user to show him how the favicon looks like on various platforms. It might be interesting to save it and present it regularly so the user is reminded what his favicon currently is.

Warning: since all files are automatically deleted after a few hours, this URL should not be saved and used as a permalink. If the picture is just supposed to be presented immediately after the favicon generation, it is ok to link to it directly. But if this picture is to be displayed at a later time, it must be downloaded and saved.

custom_parameter

This is the parameter you suplied in the request.

If, in the request, the short_url parameter was set to true, then, there is no json_result parameter in the callback URL, but a parameter named json_result_url. Its value is the URL where the JSON document (usually carried by json_result) can be downloaded. When the callback URL is triggered with this parameter, it is supposed to first download the JSON document, and then process it as if it was obtained directly via json_result.

If, in the request, the path_only parameter was set to true (in addition to short_url), the value of json_result_url is not a URL but a path. The receiver must prepend http://realfavicongenerator.net to obtain the full URL. This is to prevent a 403 error code with Hostgator hosting services.

version

This is the current version of RealFaviconGenerator. This information should be saved and used later with http://realfavicongenerator.net/api/versions (see below).

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 http://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, http://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)"
	},
	{
		"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)"
	}
]

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.

In addition, the classic change log page also supports since. For example, http://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.