Commtap Symbols Server API

This page is for developers.

About the API

We host symbol sets on our server which you can access using an API.

You can make a POST request to get:

  • Information about the symbol sets that exist on the server.
  • The license for a specific symbol set.
  • Information about a specific symbol set which contains everything required to request a symbol.
  • A symbol image.

Make a POST request to https://symbols.commtap.org/request.php with parameters as detailed below. On success a file will be returned as an attachment in the HTTP response. On failure an inline error code (or a “404 Not Found” response) will be returned.

Sending authentication information

All POST requests must include the following:

NameValue
unix_time_stampThe unix time stamp for the time the request was made. For example 1589044779.
app_codeThe identification code for your application. For example bloggs-symbol-app.
app_security_hashSHA256 hash of the concatenation of the app_code, unix_time_stamp data, and your API key (in that order). For example, in PHP you could create this hash with hash('sha256', $your_app_code . $unix_time_stamp . $your_api_key);

If you would like an identification code and API key for your application, please contact us.

List of available symbol sets – symbol-sets.csv

This provides information about the available symbol sets.

How to get the list

Make a POST request with the following parameter (in addition to the authentication information above):

NameValue
resource_typesymbol-sets-list

This will return the symbol sets list as a csv (comma separated values) file attached to the HTTP response (symbol-sets.csv).

This file contains a header row followed by a row for each symbol set. You should check the headings in the header row to ensure you are getting the right data from the symbol sets rows – the order or number of headings may change in the future.

Data contained in each column

NameValue
IdentifierA unique identifier for the symbol set. This should not change. For example maple-symbols-colour.
NameName of the symbol set which could change. For example “Maple Symbols Colour”.
AuthorAuthor or publisher of the symbol set or name of the project associated with the symbol set. For example “Maple”.
LanguageLanguage identifier. This is the ISO639-3 language code – for example “eng” for English.
CollectionFor publicly available symbols the collection is “public-symbols“.
UpdatedThe date and time the symbol set was last updated – unix time stamp.
SizeThe size in bytes of the symbol list file.
WordCountThe number of words in the set. If the same word appears more than once in the set, these are all counted.
SymbolCountThe number of images in the set.

Symbols set license

Before downloading the symbols list file for a particular set or getting any symbols from a symbol set, you must obtain the license for the set and the end user must accept it.

To do this, make a POST request with the authentication data as described above and:

NameValue
resource_typelicense
set_idThe identifier for the set, for example maple-symbols-colour.

This will return a file attachment in the HTTP response named license.txt.

The license is also available directly from: https://symbols.commtap.org/public/auto-generated/<id-of-the-symbol-set>/license.txt. Note, as this url may change, in production you should always obtain it using the POST request.

Symbols list file – <symbols-list-identifier>.csl

The symbols list file contains data about all the images and associated words in a symbol set. You can use the data from symbol-sets.csv to request a symbols list text file.

How to get a symbols list file

Make a POST request with the following parameters (in addition to those required for authenticating described above):

NameValue
resource_typesymbols-list
set_idThe identifier for the set, for example maple-symbols-colour.

Data contained in the symbols list file

This file contains all the data required to obtain symbols from the server.

Any line starting with a single quote (') is a comment. The first set of lines gives information about the symbol set. Information about symbols contained in the set appears from the first line starting with “f:“.

Note the name of the parameter is separated from its value by a colon. For example identifier:maple-symbols-colour. When reading a line of this file, you should:

  1. Trim white space from the beginning and end.
  2. Split the line into two at the first colon.
  3. Everything that was before the first colon is the name of the parameter.
  4. Everything that was after the first colon is the value of the parameter. Note the value part could contain colons. White space could appear at the beginning of the value part – so this should be trimmed.

Header information – the first few lines of the symbols list file

NameValue
identifierThe identifier for the symbols list – for example maple-symbols-colour.
nameThe name of the list – for example “Maple Symbols Colour”.
base_pathAlways \*online*\.
languageISO639-3 language code – for example “eng“.
collectionFor example “public-symbols“.
do_not_cacheAlways false for public symbols. Please always cache the symbols you request to reduce the load on the server.
date_createdThe date the file was created – unix time stamp.
authorThe name of the author, publisher or project – for example “Maple”.
author_linkURL of the author’s website if available.
info_linkURL for getting more information about the symbols set.
word_list_versionIf there is a major change to the format of the symbols list that would most likely make it not compatible with earlier versions, then this number will be incremented. There are no plans for any such changes to the format of the symbols list however.
word_list_variantThis is incremented where there are changes that should not effect compatibility with earlier versions – for example the insertion of additional name-value pairs.
word_countTotal number of words in the list. Note this includes stemmed versions of the words and is usually larger than the word count given in symbol_sets.csv.
image_countThe number of images in the set.

Symbols information

Following the header information, the rest of the file contains information about the symbols in the list.

A line beginning “f:” gives the filename for the symbol along with its file extension. The filename is a hash based on the words associated with it and the file itself. This means that if either the image is changed or the words associated with it are changed, this name will change.

Immediately following a line beginning “f:“, there are one or more further lines relating to the words for that file. Note, all the lines following a file name relate to that file up to the next line beginning “f:“.

NameValue
fFilename with extension.
w1All the words associated with the original file connected with hyphens. This is always present. For example “horse-rider-jockey”.
s1All the words in w1 stemmed and connected with hyphens. For example “horse-rid-jockey”. If s1 is the same as w1 it is not included in the file.
wThe original words associated with the file with the words separated – except those that were originally meant to be treated as a phrase. For example “horse-rider jockey”. If w is the same as s1 or w1 it is not included in the file.
sAll the words from w stemmed. Any word/phrase that does not change from w is not included. Example: “horse-rid”.

Stemming

The purpose of providing stemmed versions of the words is so that end users get more matches which are likely to be relevant for what they type. For example if they type “happiness” and the original set only contained a symbol for “happy” then they might not get anything. So that they do get something that might be relevant, and your app having searched for “happiness” in the symbols list file and not finding it, search for the stem of “happiness” which is “happi” being also the stem for “happy” – and a candidate symbol is found.

Check the code for the stemmers used on the Commtap Symbols server to help match the output of your own stemmer implementations to the outputs from these stemmers.

Request a symbol image

Send a POST request which includes the authentication information described above and:

NameValue
resource_typesymbol
set_idThe id of the symbol set, for example maple-symbols-colour.
symbolThe name of the symbol file without the extension. For example 03ccc8e0abb219ce4ab6feeacfb6aa22ed140fd8604c3564b30e6cdafce32471

The file is returned as an HTTP attachment. The filename of the attachment does not include the extension.

Returned file types

All text files are encoded in UTF16 LE (little-endian).

Images in the current symbols sets are in one of the following formats: portable network graphics (png), Windows metafile (wmf), Scalable Vector Graphics (svg). Future symbol sets may include other common image file formats.

Error response codes

If authentication fails then “404 Not Found” is returned in the HTTP header from the server. Otherwise one of the following inline response codes may be returned:

CodeMeaning
16Permission denied
17File not found
18Status undefined
19Property load error
20Empty parameter
21Unknown identifier

Caching

You should always cache the files you receive from the symbols server. The contents of the symbol sets will not change often.

Suggested work flow

  1. Get symbol-sets.csv. This will not change very often. So you could retrieve it when:
    • An end user wants to use a different symbol list.
    • If you get a file not found error when requesting a symbol.
    • Your app is started, or once a day if the app stays running.
  2. Get the symbols list file for a specific symbol set when:
    • symbol-sets.csv indicates there is a newer version of the symbol list available.
    • You get a file not found error when requesting a symbol.
  3. Symbolising:
    • First try to retrieve the required symbol locally from a cache.
    • If not stored locally, attempt to get the symbol from the Commtap symbols server.
    • If you get a file not found error, you may need to check that the symbols list hasn’t been removed from the server (unlikely) by re-downloading symbol-sets.csv. Then re-download the symbols list file for the symbol you were trying to retrieve and re-look up the symbol with the updated list.

Symbol sets

Available sets

Check details of the currently available symbol sets.

Updating and adding new symbol sets

If you would like to:

  • Add a symbol set.
  • Add symbols.
  • Update existing symbols.
  • Add additional words to existing symbols.
  • Translate a symbol set into another language.

Please do get in touch!

Donate

If you find using the Commtap Symbols Server useful, please consider making a regular donation.