Open Symbols

open-licensed communication symbols for everyone
User | Logout

OpenSymbols API Documentation


OpenSymbols is an open-licensed repository of picture symbols. You can query the API to search for symbol results that match your criteria. We are happy to support apps and web sites that would like to use the API to implement picture search inside their solution.

OpenSymbols API access requires a shared secret. Please contact us if you are interested in using OpenSymbols for search. All public APIs require an access token, which must either be set as access_token URL query parameter, or as Authorization HTTP header. Shared secrets should be kept secret, do not expose them in JavaScript or compiled application code.

To generate an access token, you will make an API call to the token endpoint as defined below and receive a short-lived access token. This can be used for multiple requests but should not be considered a long-term token.

If your access token expires you will receive a 401 HTTP response as defined in the token endpoint. If you make too many requests too quickly you will receive 429 throttling responses.

NOTE: Currently OpenSymbols returns long-term image URLs. If the usage of these URLs gets too heavy we may need to implement expiring URLs instead and ask API users to download the images for future use rather than reference them directly. We don't want to have to do this, it makes life harder for everyone, so please just be a good citizen and don't abuse things.

POST /api/v2/token

Generate access token. NOTE: Please takee the necessary precautions to secure your shared secret. This should not be accessible to the user or it will be compromised (this includes adding it as a string in a compiled app).

Query Parameters

secret
shared secret as provided by us

Results

This endpoint returns different result types than other symbols endpoints due to optimization techniques, but should be straightforward to understand:
HTTP 200
{
  "access_token": "abc123"
}

Handling Errors

When accessing endpoints using your access token, you may receive error responses. If you try to use an expired access token you will receive a 401 HTTP response with the following JSON body:

HTTP 401
{
"token_expired": true
}

When you receive token_expired you will need to make a new call to this access token generation endpoint to create a new access token. If it is easier, you are welcome to generate a new access token for each endpoint request.

Additionally we throttle requests. In general you shouldn't run into an issue with throttling, but if you do you will receive an HTTP 429 response:

HTTP 429
{
"throttled": true
}

If you are repeatedly throttled and need more access, please let us know and we can discuss solutions.

Generate an Access Token

secret
Submit

GET /api/v2/symbols

Symbol search.

Query Parameters

q
(required) search term(s), may also append repo:[repo_key] to your query to limit results a specific library, or favor:[repo_key] to favor results from a specific library, or hc:1 to favor high-contrast results
locale
language/locale to search, supports two-character locales in lowercase (es not en-US), default is en
safe
safe search, set to 0 to disable, default is enabled

Results

This endpoint returns different result types than other symbols endpoints due to optimization techniques, but should be straightforward to understand:

HTTP 200
[
  {
    "id": 2211,
    "symbol_key": "castle-1-2fcbe1a4",
    "name": "gato",
    "locale": "es",
    "license": "CC BY-NC-SA",
    "license_url": "http://creativecommons.org/licenses/by-nc-sa/3.0/",
    "author": "Sergio Palao",
    "author_url": "http://www.catedu.es/arasaac/condiciones_uso.php",
    "source_url": null,
    "skins": true,
    "repo_key": "arasaac",
    "hc": false, // (high-contrast)
    "extension": "png",
    "image_url": "https://etc...",
    "search_string": null,
    "unsafe_result": false,
    "_href": "/api/v1/symbols/arasaac/castle-1-2fcbe1a4?id=2211",
    "details_url": "/symbols/arasaac/castle-1-2fcbe1a4?id=2211",
  },
  {...},
  ...
]

Skin Tones

Some symbols have been re-rendered with different skin tones. If a symbol returns skins: true then the image url should include one of the following patterns: varianted-skin.ext where "ext" is the final file extension, or -varXXXUNI where XXX is one or more alphanumeric characters

. The reason both are possible is to allow emoji-based libraries to support skin tones without requiring as many additional uploads.

In the first place you can replace "varianted-skin" with "variant-SKINTONE", (eg. "pic.varianted-skin.png" becomes "pick.variant-dark.png" or similar), and in the second you can replace "-varXXXXXUNI" with "-SKINHEX" (eg. "1f467-var1f3fdUNI.svg" becomes "1f467-1f3fe.svg" or similar). Possible skin tones are "light" ("1f3fb"), "medium-light" ("1f3fc"), "medium" ("1f3fd"), "medium-dark" ("1f3fe"), and "dark" ("1f3ff").

Other Attributes

You may see other attributes returned in the results, but these should not be considered reliable. Also note that we do not return image dimensions or file size, sorry, we didn't need it so I haven't added it. If you are rendering via HTML consider object-fit and object-position to auto-center.

Try it out...

access_token
q
locale
safe
Submit