API Documentation

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://madaportal.org/tawasol/wp-json/custom/v2/
API routes/endpoints are then appended to this base path, like below:

http://madaportal.org/tawasol/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://madaportal.org/tawasol/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.

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://madaportal.org/tawasol/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://madaportal.org/tawasol/wp-json/custom/v2/YOUR_APP_ID/logs

to request usage statistics of your App ID.

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://madaportal.org/tawasol/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.