Dictionary Portal API

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

Introduction

This API is for expert dictionary website or APP.

What is the difference between dictionary API and dictionary PORTAL API?
Both API have same result from vocaDB.
However, Dictionary PORTAL API has no word meaning result.


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

https://vocabdb.com/v2_dic/api_vocadb_dic_PORTAL.php
Source language
  Use the slang query parameter to specify the language you want to search.
Target language
  Use the tlang query parameter to specify the language you want to search.
Source text string
  Use the q query parameter to identify the string to extract or search.
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.

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

Example of PHP curl

$params = array( 
	"slang" => 'en', 
	"tlang"=> 'ko',
	"q"=> 'arrest', 
	"level"=> 21,
	"d"=>1
);
//Convert $params into POST-ready
foreach($params as $key=>$value) 
{ 
	$data_string .= $key.'='.$value.'&'; 
}
//remove extra & in params
$data_string = rtrim($data_string, '&');

//link to VocaDB API
$ch = curl_init( "https://vocabdb.com/v2_dic/api_vocadb_dic_PORTAL.php" );
curl_setopt( $ch, CURLOPT_POSTFIELDS, $data_string );
Adding your API key in Header
//set header and apikey
curl_setopt( $ch, CURLOPT_HTTPHEADER, array( 
	'x-voca-apikey: INSERT-YOUR-KEY',
	'charset=UTF-8')
);
$result_api = curl_exec($ch);
curl_close($ch);

Query parameter reference

The query parameters you can use with the Extraction API 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 or sentence(s)
  • The text to look for relevant words or extract word list from given 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 }
d
  • Direction or Device
 { 0 | 1 } Landscape or PC : 0
Portrait or Mobile : 1

Apikey

Apikey Parameter Value Comments
apikey apikey Oauth 32 characters


Working with results

If the request succeeds, the server responds with a 200 OK HTTP status code and the data properties in JSON:

JSON format result

 { 
	"type": {-1 | 0 | 1 | 2 | 3 | 4} ,
	"contents": { 0 | -1 | -2 | -3 | [words] | [idioms] }
 }
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
Type Contents Comments
1, 2 or 3 
{
    "type": 1,
    "contents": {
        "words": {
            "voca": "arrest",
            "level": "MID2",
            "relative_words": [
                {
                    "voca": "arrest",
                    "level": "MID2",
                    "ilevel": "22"					
                },
                {
                    "voca": "arrested",
                    "level": "MID2",
                    "ilevel": "22"						
                },
                {
                    "voca": "arresting",
                    "level": "MID2",
                    "ilevel": "22"						
                },
				
			...
			
                {
                    "voca": "arrestation",
                    "level": "Master",
                    "ilevel": "42"						
                }
            ]
        },
        "idioms": {
            "relative_idioms": [
                {
                    "idiom": "be under arrest",
                    "level": "High1",
                    "ilevel": "31"						
                },
                {
                    "idiom": "house arrest",
                    "level": "Master",
                    "ilevel": "42"						
                }
            ]
        }
    }
}
Compare to
Dictionary API
4 
 
{
    "type": 4,
    "contents": {
        "trans": {
            "count": 36,
            "letters": 186
        },
        "words": {
            "relative_words": [
                {
                    "voca": "crunch",
                    "level": "高级",
                    "ilevel": "42"						
                },
                {
                    "voca": "recession",
                    "level": "高级",
                    "ilevel": "42"						
                },
                {
                    "voca": "credit",
                    "level": "高中1",
                    "ilevel": "31"						
                },
                {
                    "voca": "economist",
                    "level": "高中1",
                    "ilevel": "31"						
                }
            ]
        },
        "newwords": [
            "late-s"
        ],
        "idioms": {
            "relative_idioms": [
                {
                    "idiom": "A be considered by B to be",
                    "level": "高中2",
                    "origin": "considered by many economists to ",
                    "ilevel": "32"						
                },
                {
                    "idiom": "credit crunch",
                    "level": "高级",
                    "origin": "credit crunch",
                    "ilevel": "42"						
                },
                {
                    "idiom": "Great Depression",
                    "level": "高中2",
                    "origin": "Great Depression",
                    "ilevel": "32"						
                }
            ]
        }
    }
}
Compare to
Dictionary API
In case of tlang is "ko": 
"type": 1,
"contents": {
	"words": {
		"voca": "arrest",
		"level": "중2",
		"ilevel": "22"
In case of tlang is "en": 
"type": 1,
"contents": {
	"words": {
		"voca": "arrest",
		"level": "MID2",
		"ilevel": "22"


    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 mininum 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":1,"contents":0} Word does not exist.
    가나다라 {"type":3,"contents":0} Non-English word does not exist
Apply it Apply for APIs right now

$(document).ready(function(){ search_vocaDB( "vocaDB", 'new', true); });