vocaDB API is a paid service. Check our Pricing for detailed information.
This document explains how to get relative words from searching a word using relative word API.
The Relative API is one of vocaDB APIs and will only list up relative words and idioms with searched word.
The result from this API only gives relative words and/or idioms.
You can use this API for dictionary or tooltip service in mobile and e-learing.
What is the difference between relative word API and tooltip word API?
Both API have a search word without space but result is different.
The Relative word's result have relative words and idioms list related to a searched word.
Otherwise the result of tooltip word API are simply meaning, level, and part of speech only related to a searched word.
Search Method : English to any language vs any language to English
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_dic_relative_word.php
All parameters are required with each 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,
);
//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_dic_relative_word.php" );
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": {
"words": {
"relative_words" : []
},
"idioms": {
"relative_idioms": []
}
}
}
The query parameters you can use with the relative word 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 } | |
direction |
|
{ 0 | 1 } |
Landscape or PC : 0 Portrait or Mobile : 1 |
| Apikey | Parameter | Value | Comments |
|---|---|---|---|
apikey |
apikey | Oauth | 32 characters |
API keys are available once you Apply for API.
| Language | Parameter | Value | Comments |
|---|---|---|---|
| source | slang | Language reference | 38 Languages |
| target | tlang | Language reference | 38 Languages |
| input | q | search word | a word |
Note:
Changing tlang to a different language only affects the languages of level
of words, relative words and relative idioms. Changing slang into a different language other than en will result also to a different language on
level regardless of tlang.
Returned JSON format :
{
"type": {-1 | 0 | 1 | 3} ,
"contents": { -10 | -3 | -2 | -1 | 0 | [words] | [idioms] }
}
| Value of Type | Meaning | Comments |
|---|---|---|
| -1 | Illegal Access | Access authority |
| 0 | No result | Wrong Values |
| 1 | a word in English | { [words] | [idioms] } |
| 3 | a word in Non-English | { [words] | [idioms] } |
| Value of Contents | Format | Comments |
|---|---|---|
| -1 | {"type":-1,"contents":-1} | Wrong API key |
| -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. |
Case of English search word
{
"type": 1,
"contents": {
"words": {
"relative_words": [
{
"voca": "arrest",
"ilevel": "22",
"level": "중2",
"means": "1. 체포, 검거 2. 체포하다, 검거하다 3. 억류하다",
"part": "명,동",
"audio": "arrest"
},
. . .
{
"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"
}
]
}
}
}
Case of non-English search word
{
"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
}
]
}
}
}
