Dictionary API with REST

vocaDB API is a paid service.

This document describes common usage features of the dictionary API using the RESTful style.

Introduction

This document is intended for developers who want to develop applications utilizing dictionary API.
Dictionary API caters services for APP or dictionary website development.

Important!
Dictionary API consists of two different APIs: simple and advanced.
Simple query has no options whereas advanced query provides multiple options of queries on search result.


You can search a word from one language to another by sending an HTTP POST request to its URL.
The URL for a request has the following format:

1. Using API with simple API parameters
http://vocabdb.com/v2_dic/api_dic_vocadb.php
Source language
  Use the slang query parameter to specify the source language.
Target language
  Use the tlang query parameter to specify the target language.
Search word or text string
  Use the q query parameter to identify the string to search word or extract word list from input text.
User's Level for extract
  Use the level query parameter to get the word and idiom list from input text by user's English level.
Direction or Device
  Use the d query parameter to inform on direction or device.

Note: All parameters are required with each request

2. Using API with advanced API parameters
http://vocabdb.com/v2_dic/api_vocadb_dic.php
Source language
  Use the slang query parameter to specify the source language.
Target language
  Use the tlang query parameter to specify the target language.
Search word or text string
  Use the q query parameter to identify the string to search word or extract word list from input text.
User's Level for extract
  Use the level query parameter to get the word and idiom list from input text by user's English level.
Direction or Device
  Use the d query parameter for the server to inform direction or device.

SDE Availability (see VocaDB SDE (Synonym, Definition, Example))
  Use the definition query parameter to see the availability for SDE types.
Reference Books
  Use the ref query parameter to list the reference books for the searched word.
Relative Words or Idioms
  Use the relative query parameter to list up all related words/idioms of the searched word.
Word level
  Use the wordlevel query parameter to specify the level of searched word.
Part of speech
  Use the part query parameter to specify the given part of speech of the searched word.
Meaning
  Use the meaning query parameter to get the Meaning of the searched word.

Important!
You need to include in a custom header named x-voca-apikey, along with your API key.

Example of PHP curl

Simple query

$params = array( 
	"slang" => 'en', 
	"tlang"=> 'ko',
	"q"=> 'arrest', 
	"level"=> 21,
	"d" => 0
);

Advanced query

$params = array( 
	"slang" => 'en', 
	"tlang"=> 'ko',
	"q"=> 'arrest', 
	"level"=> 21,
	"definition" => 1,
	"ref" => 1,
	"relative" => 1,
	"wordlevel" => 0,
	"part" => 0,
	"meaning" => 0,
	"d" => 0
);
//Convert $params into POST-ready
foreach($params as $key=>$value) 
{ 
	$data_string .= $key.'='.$value.'&'; 
}
//remove lastest a extra & in params
$data_string = rtrim($data_string, '&');
Adding your API key in Header

//link to VocaDB API

//	$call_API_Path = "http://vocabdb.com/v2_dic/api_vocadb_dic.php"  // for Advanced Query
	$call_API_Path = "http://vocabdb.com/v2_dic/api_dic_vocadb.php" ; // for Simple Query

	$Call_URL_of_vocaDB = $call_API_Path;  
	$ch = curl_init($Call_URL_of_vocaDB);
	curl_setopt($ch, CURLOPT_POST, count($data_string));
	curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	
//set header and apikey	
	curl_setopt($ch, CURLOPT_HTTPHEADER, array(
					'x-voca-apikey: INSERT-YOUR-KEY',
					'charset=UTF-8' ,
					'Content-Length: ' . strlen($data_string))
	); 
	
	$result_api = curl_exec($ch);
	curl_close($ch);

Query parameters reference

All required parameters for Dictionary API (both Simple and Advance queries) are summarized in the following table.

Parameter Meaning Value Usage/Sample
APIkey Your API key 32 unique characters Users must include them in a custom header x-voca-apikey
q word & sentence(s) The text to be searched or extracted word list. arrest
slang
  • Source language
Language reference
tlang
  • Target language
Language reference
level
  • User's English level
{ 1 | 9 | 13 | 21 | 22 | 23 | 31 | 32 | 33 | 41 }
This level is used for word list extraction over user's English level from input text
d
  • Direction or Device
{ 0 | 1 | 2} 0 : Landscape or PC
1 : Portrait or Mobile
2 : iOS

The additional query parameters for Advanced query you can use with the Dictionary API are summarized in the following table.

Parameter Expression Value Selection
definition { 0 | 1 } Yes No
ref
  • Reference book
{ 0 | 1 } Yes No
relative
  • words & idioms
{ 0 | 1 } Yes No
wordlevel
  • word's level
{ 0 | 1 } Yes No
part
  • part of speech
{ 0 | 1 } Yes No
meaning
  • meaning of word
{ 0 | 1 } Yes No
d
  • Direction or Device
{ 0 | 1 | 2} Landscape or PC
Portrait or Android
iOS

Apikey

Apikey Parameter Value Comments
apikey apikey Oauth 32 characters

Four input types

Cases Example Value Comments
a word arrest English Search word
Non-English word 성공, 逮捕 38 other Languages except English Search word
words with space in order to English with space
sentence(s) The financial crisis is considered by many economists to be the worst financial crisis English limit 500 letters


Working with results

If the request succeeds, the server responds with a 200 OK HTTP status code.

JSON format result

 { 
	"type": {-1 | 0 | 1 | 2 | 3 | 4} ,
	"contents": { 0 | -1 | -2 | -3 | [words] | [idioms] }
 }
 
  	"words"  = { [words items]  | [relative_words] }
	"idioms" = { [idioms items] | [relative_idioms] }
  • Value of Type
  • Value of Type Meaning Comments
    -1 Illegal Access Access authority
    0 No result Wrong Values
    1 for a normal word { [words] }
    2 for an idiom { [idioms] }
    3 for non-English words such as 成功, 最高, 성공 { [words] | [idioms] }
    4 for word extraction 4 Groups :
    trans, { [words] | [idioms] }, newwords

    Result of "arrest"

    "words": {
    	"voca": "arrest",
    	"ilevel": "22",
    	"part": "명,동",
    	"level": "중2",
    	"pron": "어레스트",
    	"means": "1. 체포, 검거 2. 체포하다, 검거하다 3. 억류하다",
    	"audio": "arrest",
    	"ipa": "arrest",
    	"ipa_a": "əˈrest",
    	"ipa_b": "əˈrest",
    	"image": "arrest",
    	"bigimage": "arrest",
    	"definition": "1",
    	"synonym": "1",
    	"example": "1",
    	"ref": "3,4,9,11,12,25,0",
    	"relative_words": [
    		{
    		"voca": "arrested",
    		"ilevel": "22",
    		"level": "중2",
    		"means": "체포하다 [arrest의 과거/분사]",
    		"part": "동,형",
    		"audio": "arrested"
    		}
    		...
    	]
    }
    
    Parameters Return Values Comments
    voca "arrest" searched word
    ilevel "22" level of searched word
    part "명,동" part of speech
    level "중2" level of searched word using wordlevel parameter, interpreted value of level from "ilevel"
    pron "어레스트" pronunciation of the searched word
    means "1. 체포, 검거 2. 체포하다, 검거하다 3. 억류하다" meaning of searched word
    audio "arrest" filename of the audio (.mp3)
    ipa "arrest" image filename of the IPA for the searched word
    ipa_a "əˈrest" the IPA for the searched word, American
    ipa_b "əˈrest" the IPA for the searched word, Biritish
    image "arrest" filename of a creative visual/image provided by VocaDB presenting the word
    bigimage "arrest" filename of a bigger image from image
    definition "1" VocaDB SDE availability, set to 1 means Definition is available in SDE while "" means not applicable for SDE
    synonym "1" VocaDB SDE availability, set to 1 means Synonym is available in SDE while "" means not applicable for SDE
    example "1" VocaDB SDE availability, set to 1 means Example is available in SDE while "" means not applicable for SDE
    ref {3,4,9,11,12,25,0} index of 25 famous books
    relative_words [ arrested, arresting, arrestable ] List of relative words from the searched word as nested Array.
    If no relative words, the value will be 0

    Input : "arrest" , Result : " type" = 1

    200 OK
    {
    	"type":1,
    	"contents": {
    		"words":{
    	            "voca": "arrest",
    	            "ilevel": "22",
    	            "part": "명,동",
    	            "level": "중2",
    	            "pron": "어레스트",
    	            "means": "1. 체포, 검거  2. 체포하다, 검거하다  3. 억류하다",
    	            "audio": "arrest",
    	            "ipa": "arrest",  
    		    "ipa_a": "əˈrest",
    		    "ipa_b": "əˈrest",
    	            "image": "arrest",
    	            "bigimage": "arrest",
    	            "definition": "1",
    	            "synonym": "1",
    	            "example": "1"
    	            "relative_words": [
                                    {
                                        "voca" : "arrest",
                                        "ilevel" : 22,
                                        "level" : "중2",
                                        "means" : "1. 체포, 검거  2. 체포하다, 검거하다  3. 억류하다",
                                        "part" : "명,동",
                                        "audio" : "arrest"
                                    },
                                    {
                                        "voca" : "arrested",
                                        "ilevel" : 22,
                                        "level" : "중2",
                                        "means" : "체포하다 [arrest의 과거/분사]",
                                        "part" : "동,형",
                                        "audio" : "arrested"
                                    },
                                    {
                                        "voca" : arrestation",
                                        "ilevel" : 42,
                                        "level" : "고급",
                                        "means" : "억제, 정지",
                                        "part" : "명",
                                        "audio" : "arrestation"
                                    }
    					]
    			}
    		"idioms": {
    			"relative_idioms": [
    				{
    					"idiom" : "be under arrest",
    					"ilevel" : 31,
    					"level" : "고1",
    					"means" : "체포되다",
    					"audio" : "be under arrest"
    				}
    				{
    					"idiom" : "house arrest",
    					"ilevel" : 43,
    					"level" : "고급",
    					"means" : "가택 연금",
    					"audio" : "house arrest",
    				}
    			]
    
    		}
    			
    	}
    }
    

    input : "in order", Result : "type" = 2

    {
        "type" : 2,
        "contents" : {
                "idioms" : {
                        "idiom" : "in order",
                        "ilevel" : 22,
                        "level" : "MID2",
                        "means" : "1. в порядке, надлежащим образом  2. исправный",
                        "audio" : "in order",
                        "definition" : ""
                        "synonym" : ""
                        "example" : 1,
                        "relative_idioms" : [
                                    {
                                        "idiom" : "put ~ in order",
                                        "ilevel" : 21,
                                        "level" : "MID1",
                                        "means" : "Приводить ~ в порядок",
                                        "audio" : "put ~ in order"
                                    },
                                    {
                                        "idiom" : "in order to",
                                        "ilevel" : 22,
                                        "level" : "MID2",
                                        "means" : "для того,  чтобы",
                                        "audio" : "in order to"
                                    }
                            ]
                    }
            }
    }	
    

    input : "成功", Result : "type"= 3

    {
        "type": 3,
        "contents": {
           "words": {
    		"relative_words": [
    			{
    				"voca" : "wow",
    				"ilevel" : 9,
    				"part" : "感叹词",
    				"means" : "1. 轰动的成功, 叫声  2. 发出叫声, 使叫绝",
    				"level" : "言",
    				"audio" : "wow"
    			},
    			{
    				"voca" : "big",
    				"ilevel" : 13,
    				"part" : "形",
    				"means" :"1. 大, 长, 壮大  2. 爱吹牛, 成功地",
    				"level" : "小学3",
    				"audio" : "big"
    			},
    			{
    				"voca" : "succeed",
    				"ilevel" : 22,
    				"part" : "动",
    				"means" : "成功, 接替, 得手",
    				"level" : "中2",
    				"audio" : "succeed"
    			},
    			{
    				"voca" : "success",
    				"ilevel" : 22,
    				"part" : "名",
    				"means" : "成功, 成就, 顺利",
    				"level" : "中2",
    				"audio" : "success"
    			}
    		  ]
    		}
    	"idioms": {
    		"relative_idioms": [
    			{
    				"idiom" : "make one's own way",
    				"ilevel" : 22,
    				"level" : "中2",
    				"means" : "成功发迹",
    				"audio" : "make one's own way"
    			},
    			{
    				"idiom" : "succeed in ~ing",
    				"ilevel" : 23,
    				"level" : "中3",
    				"means" : "在~~(如某行业)中获得成功",
    				"audio" : "succeed in ~ing"
    			},
    			{
    				"idiom" : "make ~ of oneself",
    				"ilevel" : 32,
    				"level" : "高中2",
    				"means" : "取得成功",
    				"audio" : "make ~ of oneself",
    			},
    			{
    				"idiom" : "make one's fortune",
    				"ilevel" : 32,
    				"level" : "高中2",
    				"means" :" 成功立业",
    				"audio" : "make one's fortune",
    			},
    			{
    				"idiom" : "work one's magic",
    				"ilevel" : 32,
    				"level" : "高中2",
    				"means" : "达到成功",
    				"audio" : "work one's magic"
    			}
    		]
    	}
        }
    }
    

    input Sentences, Result : "type" = 4

    The late-2000s financial crisis (often called the global recession , global financial crisis or the credit crunch) is considered by many economists to be the worst financial crisis since the Great Depression of the 1930s.

    {
        "type" : 1
        "contents"  : {
                "trans" :  {
                        "count" : 36
                        "letters" : 186
                    },
                "words" :{
                        "relative_words" :  [
    			{
    				"voca" : "crunch",
    				"ilevel" : 42,
    				"part" : "名,動",
    				"means" : "噛み砕く, 齧る",
    				"level" : "高級",
    				"audio" : "crunch",
    				"origin" : "crunch"
    			},
    			{
    				"voca" : "recession",
    				"ilevel" : 42,
    				"part" : "名",
    				"means" : "不況, リセッション",
    				"level" : "高級",
    				"audio" : "recession",
    				"origin" :"recession"
    			},
    			{
    				"voca" : "depression",
    				"ilevel" : 41,
    				"part" : "名",
    				"means" : "憂鬱, 不況, 鬱病",
    				"level" : "大学",
    				"audio" : "depression",
    				"origin" : "depression"
    			},
    			{
    				"voca" : "credit",
    				"ilevel" : 31,
    				"part" : "名,動",
    				"means" : "クレジット, 信用, 債権",
    				"level" : "高1",
    				"audio" : "credit",
    				"origin" : "credit"
    			},
    			{
    				"voca" : "economist",
    				"ilevel" : 31,
    				"part" : "名",
    				"means" : "エコノミスト, 倹約家",
    				"level" : "高1",
    				"audio" : "economist",
    				"origin" : "economists"
    			},
    			{
    				"voca" : "considered",
    				"ilevel" : 23,
    				"part" : "動,形",
    				"means" : "考える, 看做す, 慮る",
    				"level" : "中3",
    				"audio" : "considered",
    				"origin" : "considered"
    			},
    			{
    				"voca" : "crisis",
    				"ilevel" : 23,
    				"part" : "名",
    				"means" : "危機, クライシス, ピンチ",
    				"level" : "中3",
    				"audio" : "crisis",
    				"origin" : "crisis"
    			},
    			{
    				"voca" : "depression",
    				"ilevel" : 23,
    				"part" : "名",
    				"means" : 憂鬱, 不況, 鬱病",
    				"level" : "中3",
    				"audio" : "depression",
    				"origin" : "depression"
    			},
    			{
    				"voca" : "financial",
    				"ilevel" : 23,
    				"part" : "形",
    				"means" : "融通の",
    				"level" : "中3",
    				"audio" : "financial",
    				"origin" : "financial"
    			},
    			{
    				"voca" : "consider",
    				"ilevel" : 22,
    				"part" : "動",
    				"means" : "考える, 看做す, 慮る",
    				"level" : "中2",
    				"audio" : "consider",
    				"origin" : "considered"
    			},
    			{
    				"voca" : "global",
    				"ilevel" : 22,
    				"part" : "形",
    				"means" : "グローバル, 世界的",
    				"level" : "中2",
    				"audio" : "global",
    				"origin" : "global"
    			}
    
                            ]
                "idioms" :   {
                        "relative_idioms" : [
    			{
    				"idiom" : "credit crunch",
    				"ilevel" : 42,
    				"level" : "高級",
    				"means" : "金融梗塞",
    				"audio" : "credit crunch",
    				"origin" : "credit crunch",
    			},
    			{
    				"idiom" : "financial crisis",
    				"ilevel" : 23,
    				"level" : "中3",
    				"means" : "金融恐慌, 財政危機",
    				"audio" : "financial crisis",
    				"origin" : "financial crisis"
    			},
    			{
    				"idiom" : "Great Depression",
    				"ilevel" : 32,
    				"level" : "高2",
    				"means" : "世界恐慌, {1929 年に米国に起こった}大恐慌",
    				"audio" : "Great Depression",
    				"origin" : "Great Depression"
    			},
    			{
    				"idiom" : "often called",
    				"ilevel" : 22,
    				"level" : "中2",
    				"means" : "しばしば呼ばれた",
    				"audio" : "often called",
    				"origin" :" often called"
    			}
    		]
    		}
    	}
    }
    
    


    Illegal Reference


  • Access authority Illegally
  • Value of Contents Format Comments
    -1 {"type":-1,"contents":-1} Wrong APIkey
    -2 {"type":-1,"contents":-2} Apikey Error
    -3 {"type":-1,"contents":-3} Parameters Error
    -10 {"type":-1,"contents":-10} Not allow Access
  • Value of Contents illegally
  • Value of Contents Format Comments
    0 {"type":3,"contents":0} No result
    -1 {"type":0,"contents":-1} Access Error
    -2 {"type":3,"contents":-2} Non-English word's length must have minimum 6 bytes (2 letters) for example, 눈 or 捕
    -3 {"type":3,"contents":-3} a restricted word of input word in non-English, Korean
    for examples - "이다", "する"
  • Nothing Result : Contents = 0
  • Input JSON Comments
    arrestingsil {"type":4,"contents":0} Word does not exist.
    가나다라 {"type":3,"contents":0} Non-English word does not exist