This page is for developers.
On this page
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:
| Name | Value |
unix_time_stamp | The unix time stamp for the time the request was made. For example 1589044779. |
app_code | The identification code for your application. For example bloggs-symbol-app. |
app_security_hash | SHA256 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):
| Name | Value |
resource_type | symbol-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
| Name | Value |
Identifier | A unique identifier for the symbol set. This should not change. For example maple-symbols-colour. |
Name | Name of the symbol set which could change. For example “Maple Symbols Colour”. |
Author | Author or publisher of the symbol set or name of the project associated with the symbol set. For example “Maple”. |
Language | Language identifier. This is the ISO639-3 language code – for example “eng” for English. |
Collection | For publicly available symbols the collection is “public-symbols“. |
Updated | The date and time the symbol set was last updated – unix time stamp. |
Size | The size in bytes of the symbol list file. |
WordCount | The number of words in the set. If the same word appears more than once in the set, these are all counted. |
SymbolCount | The 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:
| Name | Value |
resource_type | license |
set_id | The 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):
| Name | Value |
resource_type | symbols-list |
set_id | The 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:
- Trim white space from the beginning and end.
- Split the line into two at the first colon.
- Everything that was before the first colon is the name of the parameter.
- 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
| Name | Value |
identifier | The identifier for the symbols list – for example maple-symbols-colour. |
name | The name of the list – for example “Maple Symbols Colour”. |
base_path | Always \*online*\. |
language | ISO639-3 language code – for example “eng“. |
collection | For example “public-symbols“. |
do_not_cache | Always false for public symbols. Please always cache the symbols you request to reduce the load on the server. |
date_created | The date the file was created – unix time stamp. |
author | The name of the author, publisher or project – for example “Maple”. |
author_link | URL of the author’s website if available. |
info_link | URL for getting more information about the symbols set. |
word_list_version | If 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_variant | This is incremented where there are changes that should not effect compatibility with earlier versions – for example the insertion of additional name-value pairs. |
word_count | Total 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_count | The 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:“.
| Name | Value |
f | Filename with extension. |
w1 | All the words associated with the original file connected with hyphens. This is always present. For example “horse-rider-jockey”. |
s1 | All 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. |
w | The 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. |
s | All 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:
| Name | Value |
resource_type | symbol |
set_id | The id of the symbol set, for example maple-symbols-colour. |
symbol | The 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:
| Code | Meaning |
16 | Permission denied |
17 | File not found |
18 | Status undefined |
19 | Property load error |
20 | Empty parameter |
21 | Unknown 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
- 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.
- Get the symbols list file for a specific symbol set when:
symbol-sets.csvindicates there is a newer version of the symbol list available.- You get a file not found error when requesting a symbol.
- 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.
