Is it the right API for you? Compare the interactive and the non-interactive API.
https://
URLs.
https://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. 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
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=", ...
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
root
path
path
parameter. For example:
... "type": "path", "path": "/path/to/icons", ...
callback
type
Indicate the type of callback:
url
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
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
status
success
error
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
html_code
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_markups
will 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
path
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 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 with
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.