Dictionary API with REST

vocaDB API is a paid service. Check our Pricing for detailed information.

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.

Search word or sentence(s)

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

https://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

https://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 = "https://vocabdb.com/v2_dic/api_vocadb_dic.php"  // for Advanced Query
	$call_API_Path = "https://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 }	Landscape or PC : 0 Portrait or Mobile : 1

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`	SDE Availability (see VocaDB SDE)	{ 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 }	Landscape or PC Portrait or Mobile

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 depend on the price

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}	Expired Apikey
-3	{"type":-1,"contents":-3}	Parameters Error
-5	{"type":-1,"contents":-5}	Suspected hacking query
-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

Apply for APIs right now