Favicon generation interactive API

Invoke the service

Invoke the service by accessing https://realfavicongenerator.net/api/favicon_generatorwith 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. 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:

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 theurl 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 thecontent 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 demoparameter 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 thepath 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, theshort_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": "https://realfavicongenerator.net/files/0156213fd1232131.zip",
      "files_urls": [
        "https://realfavicongenerator.net/files/..."
      ],
      "compression": true,
      "html_code": "Html code here...",
      "overlapping_markups": [
        "link[rel=\"icon\"]",
        "meta[name=\"theme-color\"]"
      ]
    },
    "files_location": {
      "type": "path",
      "path": "/path/to/icons"
    },
    "preview_picture_url": "https://realfavicongenerator.net/files/0156213fd1232131/favicon_preview.png",
    "custom_parameter": "ref=157539001",
    "version": "0.16",
    "non_interactive_request": "... some huge string here..."
  }
}

`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.

`files_urls`

The URLs of all files contained in the package. These URLs are useful if it is not possible to unzip the zipped package (given by package_url) client side.

Because this field is quite verbose, it is present only when short_url is set to true(ie. when the JSON response must be downloaded).

Warning: since all files are automatically deleted after a few hours, this package and/or files 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.

`overlapping_markups`

This field is an array of CSS selectors that can be used to filter out existing "favicon" markups. For example, if the Safari pinned tab icon is generated, the HTML code should contain something like<link rel="mask-icon" src="mask.svg" color="#557766">. This code will probably be injected in some existing HTML pages. These pages might already declare a mask icon, which would conflict with the new one. To prevent this, overlapping_markupswill contain a selector similar to link[rel="mask-icon"]. The client can use these selectors to automatically prevent the possible duplication of markups.

`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_locationin 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 pathto 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 namedjson_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_urlis not a URL but a path. The receiver must prepend https://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 withhttps://https://realfavicongenerator.net/api/versions (see below).

`non_interactive_request`

The equivalent non-interactive request. When the end-user goes through an interactive request, he chooses various settings: the background color of the iOS icon, the compression, etc. All theses settings are saved in this non-interactive request. This request can be issued as is to re-generate the same favicon. The purpose of this feature is to allow an automated tool to update an existing favicon automatically whenever a new version is available.