vocaDB Dictionary

Why can we enter only one word when searching dictionary?
Isn't it more convenient if we can enter multiple words and get their meanings and translation simultaneously?
That's the reason we developed VocaDB Dictionary, a solution that can automatically extract words and idioms from the text. It supports 38 different languages.
Our Dictionary app is powered by VocaDB APIs including Dictionary API, SDE API (Synonyms, Definitions, Examples), User Participation API, and the APIs of Google Translate and MS Bing.
The app can search a word, extract words and idioms from an input text, provide related words and idioms, and a lot more.
This document is intended for developers who want to build mobile apps that can interact with our APIs.
To begin, you need to set up:
The app has been developed using Android Studio 2.1. It uses:
  • Android SDK 6.0, API Level 23 for Compiling
  • Android SDK 4.1, API Level 16 as Minimum SDK version
VocaDB Dictionary app is compatible with Andriod 4.1 (Jelly Bean) and up.
For more information about the configurations of the app, please check the build.gradle file under vocaDBDictionary/app.
This section provides steps on how to import VocaDB Dictionary app on your workspace and run.

Importing and Running the Application

To import the project to Android Studio:
  1. Start Android Studio and close any open Android Studio projects.
  2. From the Android Studio menu, select File > New > Import Project.
  3. Select the VocaDBDictionary project folder with the AndroidManifest.xml file and click Ok.
  4. Select the destination folder and click Next.
  5. Select the import options and click Finish.


The app uses the AQuery library for doing asynchronous tasks and manipulating UI elements. Include the .jar file under vocaDBDictionary/app/libs.
Also, add the compile dependency in build.gradle file.
compile files('libs/android-query-full.0.26.8.jar')
Other dependency libraries are also included in the file.

Project Structure

The app contains one or more modules with source code files and resource files. 
The adapters folder
This folder contains objects for making a View for each item in the data. 
The base folder
This folder contains classes that other subclasses are derived. 
The databasehelpers folder
This folder contains classes that manage database creation and version management. 
The helpers folder
This folder contains classes that provide functionalities for other classes within the app.
The models folder
This folder contains classes that model the objects associated with creating, reading, updating, and deleting.
The parsers folder
This folder contains classes that is used for parsing JSON response. 
The utilities folder
This folder contains classes that define a set of methods which perform common, often re-used functions (static).
The views folder
This folder contains classes that represent the basic building block of user interface components.

The following graphics illustrate how data flow when you start the app:


  • Splash Screen

  • Main Screen

  • Search Results

  • View Image

  • About

  • Words List

  • Idioms List

  • Synonyms List

  • Definitions List

  • Examples List

  • Idiom input

  • Phrase verb

  • Sentence Input

  • Translation by Google

  • Translation by MS Bing

The primary function of a dictionary is to provide the meaning of a particular word. Unfortunately, common dictionaries are limited to one word input. The VocaDB Dictionary app supports text or sentence inputs.

When you make a request, the API provides different return types based on four input types: normal word, idioms, non-English word, and text.

try {
    // Check first the return type
    int returnType = json.getInt("type");
    switch (returnType) {
        // Word not found
        case 0:
            wordNotFound(json); // or no authority

        // Normal word
        case 1:

        // Normal idiom
        case 2:

        // Non-english word
        case 3:

        // Extract words
        case 4:

} catch (JSONException e) {
    // TODO Auto-generated catch block
Normal Word
A plain word input with no spaces.

Normal Idiom
An input containing words with spaces.

Non-English Word
Word or character inputs such as 成功, 最高, 성공.

Word List Extraction
An input containing phrases or sentences.


Language Selection

English is the default language of the input text (source language or slang) and the search result (target language or tlang). However, the search result can be set to another language.

The app also has a reverse search function. When enabled, the system allows a non-English input text with search result in English.

The following code initialize all language and set the corresponding drawable flag based on source language (slang) and target language (tlang).

 * Method that get stored language from shared preference
private void initLanguage() {
    // Get language values from share pref
    sourceLang = prefs.getString("source_language", "");
    targetLang = prefs.getString("target_language", "");

	// Check if slang and tlang exists
    if (sourceLang.equals(""))
        sourceLang = "en";

    if (targetLang.equals(""))
        targetLang = "en";

    // Check target lang and set map image value
    if (targetLang.equals("ar"))
        languageDrawable = R.drawable.lang_arabic;
    else if (targetLang.equals("hy"))
        languageDrawable = R.drawable.lang_armenian;
    else if (targetLang.equals("bn"))
        languageDrawable = R.drawable.lang_bengali;
    else if (targetLang.equals("bg"))
        languageDrawable = R.drawable.lang_bulgaria;
    else if (targetLang.equals("zh-CN"))
        languageDrawable = R.drawable.lang_chinese_simplified;
    else if (targetLang.equals("zh-TW"))
        languageDrawable = R.drawable.lang_chinese_traditional;
    else if (targetLang.equals("hr"))
        languageDrawable = R.drawable.lang_croatian;
    else if (targetLang.equals("cs"))
        languageDrawable = R.drawable.lang_czech;
    else if (targetLang.equals("da"))
        languageDrawable = R.drawable.lang_danish;
    else if (targetLang.equals("nl"))
        languageDrawable = R.drawable.lang_dutch;
    else if (targetLang.equals("en"))
        languageDrawable = R.drawable.lang_en;
    else if (targetLang.equals("tl"))
        languageDrawable = R.drawable.lang_filipino;
    else if (targetLang.equals("fi"))
        languageDrawable = R.drawable.lang_finnish;
    else if (targetLang.equals("fr"))
        languageDrawable = R.drawable.lang_french;
    else if (targetLang.equals("ka"))
        languageDrawable = R.drawable.lang_georgian;
    else if (targetLang.equals("de"))
        languageDrawable = R.drawable.lang_german;
    else if (targetLang.equals("el"))
        languageDrawable = R.drawable.lang_greek;
    else if (targetLang.equals("hi"))
        languageDrawable = R.drawable.lang_hindi;
    else if (targetLang.equals("hu"))
        languageDrawable = R.drawable.lang_hungarian;
    else if (targetLang.equals("id"))
        languageDrawable = R.drawable.lang_indonesian;
    else if (targetLang.equals("it"))
        languageDrawable = R.drawable.lang_italian;
    else if (targetLang.equals("ja"))
        languageDrawable = R.drawable.lang_japanese;
    else if (targetLang.equals("ko"))
        languageDrawable = R.drawable.lang_korean;
    else if (targetLang.equals("ms"))
        languageDrawable = R.drawable.lang_malay;
    else if (targetLang.equals("no"))
        languageDrawable = R.drawable.lang_norwegian;
    else if (targetLang.equals("fa"))
        languageDrawable = R.drawable.lang_persian;
    else if (targetLang.equals("pl"))
        languageDrawable = R.drawable.lang_polish;
    else if (targetLang.equals("pt"))
        languageDrawable = R.drawable.lang_portuguese;
    else if (targetLang.equals("ro"))
        languageDrawable = R.drawable.lang_romanian;
    else if (targetLang.equals("ru"))
        languageDrawable = R.drawable.lang_russian;
    else if (targetLang.equals("sl"))
        languageDrawable = R.drawable.lang_slovenian;
    else if (targetLang.equals("es"))
        languageDrawable = R.drawable.lang_spanish;
    else if (targetLang.equals("sv"))
        languageDrawable = R.drawable.lang_swedish;
    else if (targetLang.equals("ta"))
        languageDrawable = R.drawable.lang_tamil;
    else if (targetLang.equals("th"))
        languageDrawable = R.drawable.lang_thai;
    else if (targetLang.equals("tr"))
        languageDrawable = R.drawable.lang_turkish;
    else if (targetLang.equals("uk"))
        languageDrawable = R.drawable.lang_ukrainian;
    else if (targetLang.equals("vi"))
        languageDrawable = R.drawable.lang_swedish;
        languageDrawable = R.drawable.lang_en; // Default flag
    languageImageView = (ImageView)findViewById(R.id.language_imageview);
    // Change button image source

Level Selection

The app has an English level selection which filters the words and idioms to be extracted from a text as well as their corresponding definitions.

If elementary level is selected, for example, it will only extract words and idioms for elementary language learners.

The app will extract with no filter if nothing is selected.


Example Text Translation

The app can also translate texts to a desired language. Just click for Google Translate and for MS Bing.


Make sure that the target language is set to a non-English language.

User Participation

The app allows users to add new words and idioms and to contribute definitions to improve the database. This feature requires user e-mail and security code.

To show the User Participation dialog, simply call the showUserParticipationDialog() function.

 * Method to show User Participation Box
public void showUserParticipationDialog(String search, int fromAdapter)
    // Instantiate dialog
    final DialogHelper dialog = new DialogHelper(MainActivity.this, R.style.modalDialog);
    // Set dialog layout

    // Set modal screen size
    int width = ViewGroup.LayoutParams.MATCH_PARENT;
    int height = ViewGroup.LayoutParams.MATCH_PARENT;
    dialog.getWindow().setLayout(width, height);

    // Set title for the dialog
    dialog.setTitle("User Participation");

    // Show dialog

    // Find views
    final EditText word = (EditText) dialog.findViewById(R.id.word_edittext);
    final EditText wordMeaning = (EditText) dialog.findViewById(R.id.word_meaning_edittext);
    final EditText partOfSpeech = (EditText) dialog.findViewById(R.id.part_of_speech_edittext);
    final EditText clientsEmail = (EditText) dialog.findViewById(R.id.clients_email_edittext);
    final EditText securityCode = (EditText) dialog.findViewById(R.id.security_code_edittext);
    ImageView closeImageView = (ImageView) dialog.findViewById(R.id.close_imageview);
    Button submit = (Button) dialog.findViewById(R.id.submit_button);

    // Set prefilled value to word
    if (!TextUtils.isEmpty(sourceEditText.getText().toString()) && fromAdapter == 0)

    // Button click event
    submit.setOnClickListener(new View.OnClickListener() {
        public void onClick(View v) {
            // Get edittext values
            String wordStr = word.getText().toString();
            String wordMeaningStr = wordMeaning.getText().toString();
            String partOfSpeechStr = partOfSpeech.getText().toString();
            String clientsEmailStr = clientsEmail.getText().toString();
            String securityCodeStr = securityCode.getText().toString();

            // Check first if there are no empty fields
            if (TextUtils.isEmpty(wordStr)){
                focusView = word;
                cancel = true;

            if (TextUtils.isEmpty(wordMeaningStr)){
                focusView = wordMeaning;
                cancel = true;

            if (TextUtils.isEmpty(partOfSpeechStr)){
                focusView = partOfSpeech;
                cancel = true;

            if (TextUtils.isEmpty(clientsEmailStr)){
                focusView = clientsEmail;
                cancel = true;
            } else if (!vocaDBUtils.isEmailValid(clientsEmailStr)) {
                focusView = clientsEmail;
                cancel = true;

            if (TextUtils.isEmpty(securityCodeStr)){
                focusView = securityCode;
                cancel = true;
            // Check if security code is correct
            else if (!securityCodeStr.equals("2637")) {
                focusView = securityCode;
                cancel = true;

            if (cancel) {
                // There was an error; don't attempt register and focus the first
                // form field with an error.
                cancel = false;
            } else {
                String url = Constants.USER_PARTICIPATION_URL;
                Map params = new HashMap();
                params.put("apikey", Constants.DICTIONARY_API_KEY);
                params.put("word", wordStr);
                params.put("means", wordMeaningStr);
                params.put("pos", partOfSpeechStr);
                params.put("email", clientsEmailStr);
                params.put("tlang", targetLang);
                AQUtility.debug("Parameters", params);
                aq.ajax(url, params, JSONArray.class, new AjaxCallback() {
                    public void callback(String url, JSONArray _ja, AjaxStatus _status) {
                        AQUtility.debug("User Participation Response", _ja);

                        // Prompt user for success
                        new AlertUtility(MainActivity.this).alertInfo(
                                "User Participation",
                                "Thank you for your participation.",

                        // Close dialog

    // Set close button click listener
    closeImageView.setOnClickListener(new View.OnClickListener() {
        public void onClick(View v) {
            // Close dialog

Word Puzzle

The app also has a puzzle feature for easy memorization of searched words. The color of each letter changes when clicked.

To show puzzle, simply call the createPuzzle() function.

 * Method to create puzzle
 * @param word
private void createPuzzle(final String word) {
    AQUtility.debug("Puzzle word count:", word.length());
    // Remove all existing views in the layout
    String[] str = word.split("");
    List textList = new ArrayList(wordCount);
    for(int i = 0; i <= word.length(); i++) {
        AQUtility.debug("Puzzle word count:", word.length());
        AQUtility.debug("Puzzle word char:", str[i]);
        final TextView letterTextView = new TextView(MainActivity.this);
        LinearLayout.LayoutParams param = new LinearLayout.LayoutParams(LinearLayout.LayoutParams.WRAP_CONTENT,
        param.rightMargin = 5;
        letterTextView.setTypeface(null, Typeface.BOLD);
        letterTextView.setPadding(0, 10, 0, 10);
        letterTextView.setOnClickListener(new View.OnClickListener() {
            public void onClick(View v) {
                if (letterTextView.getCurrentTextColor() == Color.RED)
    // Add speaker imageview
    ImageView speakerImageView = new ImageView(MainActivity.this);
    LinearLayout.LayoutParams param = new LinearLayout.LayoutParams(45,45);
    speakerImageView.setOnClickListener(new View.OnClickListener() {
        public void onClick(View v) {
            wordCount = VocaDBUtils.countWords(word);
            Log.d("Word count", String.valueOf(wordCount));
            // Check first if input is not empty
            if (wordCount > 0) {
                if (isInternetPresent()) {
                    if (isPlaying) {

                    try {
                        isPlaying = true;
                        // Check first if audio already exists in the local directory
                        if(!new File(Environment.getExternalStorageDirectory().toString() + Constants.AUDIO_PATH + searchValue.toLowerCase() + ".mp3").exists()) {
                            new DownloadFileFromURL("audio").execute(Constants.MEDIA_URL + searchValue.toLowerCase() + ".mp3");
                            mediaPlayer.setDataSource(Constants.MEDIA_URL + searchValue.toLowerCase() + ".mp3");
                        } else {
                            // Load audio from local directory
                            mediaPlayer.setDataSource(Environment.getExternalStorageDirectory().toString() + Constants.AUDIO_PATH + searchValue.toLowerCase() + ".mp3");

                    } catch (IllegalArgumentException e) {
                        isPlaying = false;
                    } catch (SecurityException e) {
                        isPlaying = false;
                    } catch (IllegalStateException e) {
                        isPlaying = false;
                    } catch (IOException e) {
                        isPlaying = false;
                } else {
                    // Check if tts is in play/pause mode
                    if (!play) {
                        play = true;
                        textToSpeech = new TextToSpeech(getApplicationContext(),
                                new TextToSpeech.OnInitListener() {
                                    public void onInit(int status) {
                                        Log.d("MP Status", String.valueOf(status));
                                        if (status != TextToSpeech.ERROR) {
                                            Locale locale = new Locale(db.getLanCode(prefs.getString("default_language", "")));
                                            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
                                            } else {
                    } else {
                        play = false;
            } else {
                Toast.makeText(MainActivity.this, "No word or text", Toast.LENGTH_SHORT).show();
The Dictionary API allows developers to make requests and get responses in JSON format.


The API key for this app is defined in app/your_app_package_name/base/Constants.java.
// API Keys
public static final String DICTIONARY_API_KEY = "YOUR_API_KEY";

Apply for API Key


All URLs are defined also in app/your_app_package_name/base/Constants.java.
public static final String BASE_URL = "https://www.vocadb.com/v2_dic/";

public static final String DICTIONARY_API_URL = BASE_URL + "api_vocadb_dic.php";

public static final String DEFINITION_API_URL = BASE_URL + "api_dic_exam_def.php";
public static final String EXAMPLE_DEF_TRANS_API_URL = BASE_URL + "api_dic_exam_def_trans.php";
public static final String USER_PARTICIPATION_URL = BASE_URL + "api_dic_request_word.php";
It is important to add the custom header named x-voca-apikey, along with your API key.
httpPost.addHeader("x-voca-apikey", YOUR_API_KEY);
Also, don't forget to add UTF-8 encoding type to the request.
httpPost.setEntity(new UrlEncodedFormEntity(params, "UTF-8"));


The parameters needed to make a request are:
  • slang - Source language reference
  • tlang - Target language reference
  • level - User-defined level for extraction
  • q - Searched word
  • d - Direction, 1 = mobile

Sample Inputs

User can enter four (4) types of inputs:
  1. Type=1 for a word
  2. Type=2 for a Idiom
  3. Type=3 for a Non-English text
  4. Type=4 for Sentence

Sample Request

For more information on API, click the button below:

Dictionary API Documentation

Download the App!
Get it on Google Play


© vocaDB. All rights reserved.