Skip to content

Latest commit

 

History

History
58 lines (41 loc) · 2.66 KB

API.md

File metadata and controls

58 lines (41 loc) · 2.66 KB

Service API reference

Overview

Favicon Grabber API is simple and has the one endpoint. The API does not require authentication but has the following restrictions: 100 requests per minute from one IP address and each API request should specify a valid User-Agent header.

The root endpoint for the API is https://favicongrabber.com/api and all responses are returned as JSON(P) over HTTP.

The API supports requests and responses using Cross-Origin Resource Sharing so you can send XHR requests from browsers using a client-side web application served from any domain.

Grab favicons

In order to grab favicons for a website send a GET request to the API endpoint /api/grab/:domain, where :domain is a required parameter that should be equal to the valid domain name syntax.

For instance, to grab favicons from github.com domain open https://favicongrabber.com/api/grab/github.com in your favorite browser and you must see next JSON response:

{
  "domain": "github.com",
  "icons": [
    {
      "src": "https://assets-cdn.github.com/favicon.ico",
      "type": "image/x-icon"
    },
    {
      "src": "https://assets-cdn.github.com/pinned-octocat.svg"
    },
    {
      "src": "https://github.com/fluidicon.png"
    }
  ]
}

Property domain contains the value of :domain parameter. The property icons contains an array of icon objects and may be empty. Any icon object can have three properties, the values of which are strings.

Description properties of icon object:

  • property src contains an absolute URL for a favicon image and is required and unique;
  • property type equals an MIME-type's favicon image;
  • property sizes contains size's favicon image and in a simple case has the following format: HEIGHTxWIDTH in pixels (for a full description, see HTML5 Links).

Optional parameters

There are two optional parameters for the API:

  • pretty=true for formatting JSON response;
  • callback=done for JSONP response, where done is a variant of the name of the JSONP function.

Error handling

The API uses HTTP response codes to indicate API errors. All error messages have the following format:

{
  "error": "Unresolved domain name."
}