Relative word API with REST

vocaDB API is a paid service. Check our Pricing for detailed information. For free version check out vocaDB Dictionary Website.

This document explains how to get relative words from searching a word using relative word API.

Introduction

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

Working with results

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:

http://vocabdb.com/v2_dic/api_vocadb_relativ_word.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 a word
  Use the q query parameter to identify the string without space to search.
User's Level
  Use the level query parameter to get the word and idiom list from input word by user's English level.

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( "http://vocabdb.com/v2_dic/api_vocadb_relativ_word.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);

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

input : "arrest", Result : "type"= 1, source language(slang) = en, target language(tlang) = ko

{ 	"type": 1,
	"contents": {
		"words": {
			"relative_words" : []
		},
		"idioms": {
			"relative_idioms": []
		}
	}
}

Query parameter reference

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
  • Source language
Language reference
tlang
  • Target language
Language reference
level
  • User's English level
{ 1 | 9 | 13 | 21 | 22 | 23 | 31 | 32 | 33 | 41 }
direction
  • Direction or Device
{ 0 | 1 } Landscape or PC : 0
Portrait or Mobile : 1

Apikey

Apikey Parameter Value Comments
apikey apikey Oauth 32 characters

API keys are available once you Apply for API. Log into our API Management to get your API key.

Languages and Input word

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.

Sample query : a word only

Result Value of API

Returned JSON format :

 { 
	"type": {-1 | 0 | 1 | 3} ,
	"contents": { -10 | -3 | -2 | -1 | 0 | [words] | [idioms] }
 }
	

  • JSON format
  • Value of Type
  • 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] }
  • Access authority illegally
  • Value of Contents Format Comments
    -1 {"type":-1,"contents":-1} Wrong API key
    -2 {"type":-1,"contents":-2} Api key Error
    -3 {"type":-1,"contents":-3} Parameters Error
    -10 {"type":-1,"contents":-10} Access denied
  • Value of Contents
  • Value of Contents Format Comments
    0 {"type":0,"contents":0} No result
    0 {"type":0,"contents":-1} No result, Search word has space

    Case of English search word

    input : "arrest", Result : "type"= 1, source language(slang) = en, target language(tlang) = ko

    {
    	"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

    input : "成功", Result : "type"= 3, source language(slang) = chinese(zh-CN), target language(tlang) = en

    {
        "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
    			}
    		]
    	}
        }
    }
    
Apply it Apply APIs right now