vocaDB API is a paid service. Check our Pricing for detailed information.
This document explains common features of Simple word API using the RESTful style.
The Simple API has two kinds: word and text API for search word.
If a searched word has no space, it is called Simple word API not Simple text API.
What is the difference between dictionary API and Simple word API?
Simple word API
has simplified result from vocaDB on searched word.
The results are meaning, level, image and part of speech.
User can understand word's meaning easily by using pop up windows on mobile or PC.
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:
https://vocabdb.com/v2_dic/api_dic_tooltip_word.php
Three query parameters are required with each search request:
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, "direction"=>0 ); //Convert $params into POST-ready foreach($params as $key=>$value) { $data_string .= $key.'='.$value.'&'; } //remove extra & in params $data_string = rtrim($data_string, '&'); //Check if the searched word has space or not. if($this->input->post('space_cnt') > 0) { $link = LINK_Simple_TEXT; } else { $link = LINK_Simple_WORD; } $ch = curl_init( $link ); curl_setopt( $ch, CURLOPT_POSTFIELDS, $data_string );
//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);
If the request succeeds, the server responds with a 200 OK
HTTP status code and the data properties in JSON:
{ "type": 1, "contents": { "voca": "insist", "part": "동", "level": "중3", "means": "1. 주장하다 2. 강조하다", "image": "89652" } }
All required parameters for Simple 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 |
search word | The input only accepts a word without space. | arrest |
slang |
|
Language reference | |
tlang |
|
Language reference | |
level |
|
{ 1 | 9 | 13 | 21 | 22 | 23 | 31 | 32 | 33 | 41 } | |
d |
|
{ 0 | 1 } |
Landscape or PC : 0 Portrait or Mobile : 1 |
API keys are available once you Apply for API. Log into our API Management to get your APIkey.
Note:
At least one (1) of the languages (Source language slang
or Target language tlang
) must be in English (en
) for the request to work.
Cases | Example | Value | Comments |
---|---|---|---|
a word | arrest | English | Search word |
a word (not English) | 성공, 逮捕 | search word must have English word. | No Result |
Returned JSON format :
{ "type": {-1 | 0 | 1 | 2 | 3 | 4} , "contents": { 0 | -1 | -2 | -3 | word} } "word" = { voca, means, part, level, image }
The result consists of type and content parts.
Value of Type | Meaning | Comments |
---|---|---|
-1 | Illegal Access | Access authority |
0 | No result | Wrong Values |
1 | for a normal word | { "contents" } |
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 |
-10 | {"type":-1,"contents":-10} | Access denied |
Value of Contents | Format | Comments |
---|---|---|
0 | {"type":0,"contents":0} | No result |
-1 | {"type":0,"contents":-1} | No result because the search word is not complete. |
-2 | {"type":0,"contents":-2} | No result, the search word is non-English. |
-3 | {"type":0,"contents":-3} | No result, the search word has space. |
Type | Contents | Comments |
---|---|---|
1 |
{ "type": 1, "contents": { "voca": "financial", "part": "형", "level": "중3", "means": "재정의, 자금의", "image": "odsjds956" } } |
success searched |
0 |
{ "type": 0, "contents": 0 } |
No result |
Input | JSON | Comments |
---|---|---|
arrestingsil | {"type":0,"contents":0} | Word does not exist. |
가나다라 | {"type":0,"contents":0} | Non-English word does not exist |