Icon keywords

API query /keywords is intended to be used for suggesting search queries.

Query

API query is /keywords.

There are two variations of this query, depending on passed parameters.

You must set one of the following parameters:

• prefix, string. Keyword prefix. API returns all keywords that start with requested keyword.
• keyword, keyword. Partial keyword. API returns all keywords that start or end with requested keyword.

If you set both prefix and keyword parameters, keyword parameter will be ignored.

Keyword

This is a very basic function. It can handle only one keyword, not multiple keywords.

Keyword requirements:

• Can contain only letters "a" - "z", numbers and "-".
• If it contains "-", only last part after "-" is checked, the rest is ignored.
• Must be at least 2 characters long.

Response

Response is an object, which contains all properties passed in query and the following properties:

• invalid, boolean. Set to true if keyword is invalid.
• exists, boolean. Set to true if keyword exists as full keyword (with nothing or "-" before and after it in icon name).
• matches, [type]string[]`. List of matches.

Examples

json{
   "prefix": "hom",
   "pretty": "1",
   "exists": false,
   "matches": [
       "home",
       "home2",
       "home3",
       "homee",
       "homify",
       "homewav",
       "homebrew",
       "homestay",
       "homebridge",
       "homeadvisor",
       "homeassistant",
       "homeassistantcommunitystore"
   ]
}

/keywords?prefix=hom&pretty=1

json{
   "keyword": "home",
   "pretty": "1",
   "exists": true,
   "matches": [
       "home2",
       "home3",
       "homee",
       "homewav",
       "homebrew",
       "homestay",
       "homebridge",
       "homeadvisor",
       "homeassistant",
       "homeassistantcommunitystore",
       "esphome",
       "ourhome",
       "eufyhome",
       "googlehome",
       "petsathome",
       "vectorifydahome"
   ]
}

/keywords?keyword=home&pretty=1

Error response

If no matches found or keyword is too short, correct response is returns with matches object being empty:

json{
   "keyword": "qwerty",
   "exists": false,
   "matches": []
}

If keyword is invalid, response includes invalid property set to true:

json{
   "keyword": "_",
   "invalid": true,
   "exists": false,
   "matches": []
}

If search engine is disabled, /keywords route is not handled, server returns 404 HTTP error.

Type

Type for API response:

ts/**
* Parameters for `/keywords` query
*
* One of `prefix` or `keyword` parameters must be set
*/
export interface APIv3KeywordsPrefixQuery {
   // Prefix to test: matches for 'foo' include 'foobar', but not 'barfoo'
   prefix: string;
}

export interface APIv3KeywordsFullQuery {
   // Keyword to test: matches for 'foo' include 'foobar' and 'barfoo'
   keyword: string;
}

export type APIv3KeywordsQuery =
   | APIv3KeywordsPrefixQuery
   | APIv3KeywordsFullQuery;

/**
* Response for /keywords query
*
* Includes request + response
*/
export type APIv3KeywordsResponse = APIv3KeywordsQuery & {
   // Set to true if keyword is invalid
   invalid?: true;

   // True if partial keyword exists as is
   exists: boolean;

   // Keywords that contain partial keyword
   matches: string[];
};