1.Introduction #

Tawasol provides a simple, lightweight and portable API in JSON format of frequently used words in spoken and written communication represented by images and pictograms.

Data from the Tawasol API are suitable for use in every framework, language and application.

Connecting To The API

We serve our data in JSON format via a simple URL-based interface over HTTPS, which enables you to use the symbols in whichever way you require.
Any language or software that can make HTTP requests or fetch web addresses can access our API. You can use whichever library you require depending on your development environment.
URLs (routes) requested over HTTPS deliver all the data in one go, just like a normal web request.

URL Format

The API base path is http://tawasolsymbols.org/wp-json/custom/v2/
API routes/endpoints are then appended to this base path, like below:

http://tawasolsymbols.org/wp-json/custom/v2/
                                  symbols
                                  symbol_categories
                                  lexical_core_categories

If your request is valid and permitted, you will receive a JSON-formatted response to work with. If something is wrong with the request, you will receive an error message.

API Response Formats

Responses are delivered over HTTPS as plain-text JSON (JavaScript Object Notation) format, ready to be used however your integration requires.
This format doesn’t limit how and where you can use the data in any way: JSON is simply a fast, simple and lightweight delivery mechanism, which is supported in every major language and framework.
Here’s an example basic API request for all the symbols:

HTTP

 http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/symbols 

When requesting this URL (assuming your App ID is valid) you will receive a JSON object containing all the relevant data like below:

JSON – symbols

{
    symbol_id: "1",
    lexical_entry_id: "2",
    creator_id: "2",
    source_id: "ذَهَبَ",
    description: "1",
    language: "MSA",
    image_uri: "/Designer/Go (M).png",
    created_at: "2016-05-08 10:03:48",
    undiac_description: "ذهب",
    symbol_category: {....}
    lexical_category: {....}    
}

Each API route has a different request and response format. Please see their relevant pages for details and examples.

Yes No

2.Authentication #

The Tawasol API currently supports basic App ID authentication. App ID is a 10-character alphanumeric identifier unique to each account.App IDs should be kept as secret as possible.

Register for App Id

You can register here to generate your App ID.
If you are a registered developer, you can visit your account dashboard to view your App ID any time.

How to use Your App ID

To access any of the API routes, you simply need to append your App ID to each of your request like below:

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/symbols

Track Your App ID Usage

You can log in to your account dashboard and view your App ID Usage Statistics.
You can also use logs API endpoint:

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/logs

to request usage statistics of your App ID.

Yes No

3.Errors #

The Tawasol API routes will return JSON error messages if invalid App ID is provided or you don’t have permission to access data.
All Tawasol API errors use the same format.

Example of an error produced when an invalid app_id is provided is as below:

{
    error: "true",
    status: "401",
    message: "Invalid App ID provided. Please sign up at http://tawasolsymbols.org/en/developer-registration to generate your App ID."
}

Error Status Codes Reference

The most common errors are listed below:

Message Status Code Details

“not_found”

404

Non-existent resource/route requested

“missing_app_id”

401

App ID not provided

“invalid_app_id”

401

Invalid App ID provided

**If you get an error that is not documented here, or experience some other issue with our API, please contact us.

Yes No

4.API Endpoints #

4.1./symbols #

Get the list of all the latest symbols available from Tawasol API.

URL Format

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/symbols

Parameters

APP ID(your unique app id):string (required)

Result Format

200 OK
{
    symbol_id: "1",
    lexical_entry_id: "2",
    creator_id: "2",
    source_id: "1",
    description: "ذَهَبَ",
    language: "MSA",
    image_uri: "/Designer/Go (M).png",
    created_at: "2016-05-08 10:03:48",
    undiac_description: "ذهب",
    symbol_category: {....}
    lexical_category: {....}    
}
{....}

Errors

Please see API Error Messages for a list of possible errors.

Yes No

4.2./symbol_categories #

Get the list of all the categories of symbols available from Tawasol API.

URL Format

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/symbol_categories

Parameters

APP ID(your unique app id):string (required)

Result Format

200 OK
{
    symbol_category_id: "1",
    name: "Colour"
}
{
    symbol_category_id: "2",
    name: "Male"  
}
{.....}

Errors

Please see API Error Messages for a list of possible errors.

Yes No

4.3./lexical_core_categories #

Get the list of all the core lexical categories of symbols available from Tawasol API.

URL Format

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/lexical_core_categories

Parameters

APP ID(your unique app id):string (required)

Result Format

200 OK
{
    lexical_entry_category_id: "3",
    name: "Core"
}
{
    lexical_entry_category_id: "59",
    name: "Dual"  
}
{.....}

Errors

Please see API Error Messages for a list of possible errors.

Yes No

4.4./lexical_non_core_categories #

Get the list of all the sub lexical categories of symbols available from Tawasol API.

URL Format

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/lexical_non_core_categories

Parameters

APP ID(your unique app id):string (required)

Result Format

200 OK
{
    lexical_entry_category_id: "1",
    name: "Actions"
}
{
    lexical_entry_category_id: "49",
    name: "Adjectives"  
}
{.....}

Errors

Please see API Error Messages for a list of possible errors.

Yes No

4.5./symbol #

Get all the information of a particular symbol requested from Tawasol API.

URL Format

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/symbol/SYMBOL_NAME

Parameters

APP ID(your unique app id):string (required)]
SYMBOL_NAME(name of symbol):string (required)

Example

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/symbol/good

Result Format

200 OK
{
    symbol_id: "803",
    lexical_entry_id: "562",
    creator_id: "3",
    source_id: "2",
    description: "good",
    language: "en",
    image_uri: "/ARASAAC/good!.png",
    created_at: "2014-04-13 17:40:00",
    undiac_description: "good",
    symbol_category: {....}
    lexical_category: {....}    
}

Errors

Please see API Error Messages for a list of possible errors.

Yes No

4.6./category #

Get information of all symbols belonging to a particular category requested from Tawasol API.

URL Format

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/category/CATEGORY_NAME

Parameters

APP ID(your unique app id):string (required)]
CATEGORY_NAME(name of category):string (required)

Example

http://tawasolsymbols.org/wp-json/custom/v2/YOUR_APP_ID/category/masculine

Result Format

200 OK
{
    lexical_entry_id: "4",
    creator_id: "1",
    language: "MSA",
    pos: "verb",
    phonemes: "يَ نْ ظُ ر",
    description: "He looks",    
    lexical_entry_category_id: "4"  
}
{....}

Errors

Please see API Error Messages for a list of possible errors.

Yes No

5.Help & Support #

Please see API Error Messages for a list of possible errors.

If you get an error that is not documented in our API Error Messages section, or experience some other issue with our API, please contact us.

Yes No