SDE API with REST(Synonyms, Definitions and Examples)

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

This document explains additional usage information of Synonyms, Definition and Example API (VocaDB SDE).

Introduction

This document is intended for developers who want to write applications that can interact with the vocaDB and SDE API.

To use SDE API, users must check the JSON result of Dictionary API with parameter definition, synonym, or example set to 1

	"words": {
		"voca": "arrest",
		"ilevel": "22",
		"part": "명,동",
		"level": "중2",
		...
		"definition": "1",
		"synonym": "1",
		"example": "1",
		...

Upon checking Dictionary API's JSON result, under words, check for the values of synonym, definition and example.
if the value is set to "1" then the searched word can be used in the SDE API respectively.
Also, you can use SDE API independently.

Search word or sentence(s)

The URL for a request has the following format:

https://vocabdb.com/v2_dic/api_dic_exam_def.php

Mode: Use the mod query parameter to specify the type to determine synonyms, definition and example
Level: Use the level query parameter to specify the user's English level.
SDE word: Use the q query parameter to identify the word for searching SDE.
Target language: Use the tlang query parameter to specify the target language.
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(
	"mod" => 1,
	"q" => 'arrest', 
	"level"=> 21,
	"tlang"=>ko,
	"d"=>0
);

/*
|	"mod = 1" => Examples
|	"mod = 2" => Definition
|	"mod = 3" => Synonyms
|	"mod = 4" => in case of input with space (idiom)

|   "d = 0" => PC
|   "d = 1" => Mobible
|
*/

//Convert $params into POST-ready
foreach($params as $key=>$value) 
{ 
	$data_string .= $key.'='.$value.'&'; 
}
//remove extra & in params
$data_string = rtrim($data_string, '&');

Adding your API key in Header

//link to VocaDB API
	$curl_file = "https://vocabdb.com/v2_dic/api_dic_exam_def.php" ;
	$ch = curl_init($curl_file);
	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')
	);
	$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:

JSON

// type 1
{
	"type": "1"
	"contents": [
		{
			"level": "MID"
			"grade": "2"
			"book": "Didimdol_Kim"
			"example": "At the news of Rosa Parks' arrest, the black people got upset and started a bus boycott."
		}
		...
	]
}
// type 2
{
	"type": "2"
	"contents": [
		{
			"level": "D"
			"example": "attract and fix"
		},
		{
			"level": "S"
			"example": "Arrest the downward trend; Check the growth of communism in South East Asia; Contain the rebel movement; Turn back the tide of communism"
		}
		...
	]
}
//type 3
{
	"type": "3"
	"contents": [
		{
			"level": "ant"
			"example": "release, dismiss"
		},
		{
			"level": "syn"
			"example": "seize, apprehend, capture"
		}
		...
	]
}

Parameter	Meaning	Notes
`APIkey`	Your API key	This API requires a valid key for all requests. Users must include them in a custom header `x-voca-apikey`
`q`	search word	query parameter to identify the word for searching SDE.
`mod`	Mode	Selection mod. Result is dependent on this parameter. mod = 1 refers to `Examples of word` mod = 2 refers to `Definition` mod = 3 refers to `Synonyms` mod = 4 refers to `Examples of idiom that must have space`
`level`	Level	The User's English level.
`d`	Device	0 : PC, Landscape 1 : Mobile, Portrait

Note: The mod parameter is strict, it can only be 1, 2, or 3 or the request won't work.

Apikey

Apikey	Parameter	Value	Comments
`apikey`	apikey	Oauth	32 characters

API keys are available once you Apply for API.

Sample query

Mode	Example
Examples `mod 1`	"q" : "arrest", "mod" : "1", "level" : "21"
Definition `mod 2`	"q" : "arrest", "mod" : "2", "level" : "21"
Synonyms `mod 3`	"q" : "arrest", "mod" : "3", "level" : "21"
Examples of idiom or phrase verb `mod 4`	"q" : "by the way", "mod" : "4", "level" : "21"

Return JSON format

Mode	Example
Examples `mod 1`	{ type "mod 1" for Examples contents: [ level Used in Extraction level grade Grade or Chapter book Book Source example Example Sentence ] }
Definition `mod 2`	{ type "mod 2" for Definition contents: [ level "D" for Definition, "S" for Sentence example Example definition or sentence ] }
Synonyms `mod 3`	{ type "mod 3" for Synonyms contents: [ level "syn \| ant" - "syn" for Synonyms, "ant" for Antonyms example example synonyms or antonyms ] }

Returned JSON format :

{ 
	"type": { -1 | 0 | 1 | 2 | 3} ,
	"contents": { -3 | -2 | -1 | 0 | [array('level','example')] | [array('level','grade','book','example')] }
}

JSON format

The result consists of types and contents parts.

Value of Type

Value of Type	Meaning	Comments
-1	Error	{ -10 \| .. \| -1 }
0	Error or No Result	{ -1 \| 0 }
1	Synonyms	{ [{'level','grade','book','example'}] }
2	Definition	{ [{'level','example'}] }
3	Example	{ [{'level','example'}] }

Access authority illegally

Value of Contents	Format	Comments
0	{"type":0,"contents":0}	No Result
0	{"type":0,"contents":-1}	Access Error
-1	{"type":-1,"contents":-1}	Wrong APIkey
-2	{"type":-1,"contents":-2}	Expired Apikey
-3	{"type":-1,"contents":-3}	Parameters Error
-3	{"type":-1,"contents":-4}	MS Bing does not support language for translation
-10	{"type":-1,"contents":-10}	Access denied

Result Value of sample query

Result	Type 1

{
	"type": "1",
	"search": "arrest",
	"contents": [
	{
		"level": "MID",
		"grade": "2",
		"book": "Didimdol_Kim",
		"example": "At the news of Rosa Parks' arrest, the black people got upset and started a bus boycott."
	},
	{
		"level": "MID",
		"grade": "3",
		"book": "Jihaksa",
		"example": "You're under arrest."
	},
	{
		"level": "MID",
		"grade": "3",
		"book": "Jihaksa",
		"example": "Under arrest?"
	},
	{
		"level": "MID",
		"grade": "3",
		"book": "Accom",
		"example": "But at last he was arrested, thanks to the dog."
	},
	{
		"level": "MID",
		"grade": "3",
		"book": "Accom",
		"example": "She arrested the man."
	},
	{
		"level": "MID",
		"grade": "2",
		"book": "Didimdol_Kim",
		"example": "The driver called the police, and she was arrested."
	}
	]
}

Result	Type 2

{
	"type": "2",
	"search": "arrest",	
	"contents": [
		{
			"level": "D",
			"example": "attract and fix"
		},
		{
			"level": "D",
			"example": "hold back, as of a danger or an enemy; check the expansion or influence of"
		},
		{
			"level": "D",
			"example": "take into custody"
		},
		{
			"level": "D",
			"example": "the act of apprehending (especially apprehending a criminal)"
		},
		{
			"level": "D",
			"example": "the state of inactivity following an interruption"
		},
		{
			"level": "D",
			"example": "to catch and hold someone because he has broken a law"
		},
		{
			"level": "D",
			"example": "to seize a person for legal action; to take as a prisoner"
		},
		{
			"level": "S",
			"example": "Arrest the downward trend; Check the growth of communism in South East Asia; Contain the rebel movement; Turn back the tide of communism"
		},
		{
			"level": "S",
			"example": "the negotiations were in arrest; held them in check; during the halt he got some lunch; the momentary stay enabled him to escape the blow; he spent the entire stop in his seat"
		},
		{
			"level": "S",
			"example": "the policeman on the beat got credit for the collar"
		}
	]
}

Result	Type 3

{
	"type": "3",
	"search": "arrest",	
	"contents": [
		{
			"level": "ant",
			"example": "release, dismiss"
		}
		{
			"level": "syn",
			"example": "seize, apprehend, capture"
		}
		{
			"level": "syn",
			"example": "seize, take, stop, capture, withhold, restrain, hold, detain, apprehend"
		}
		{
			"level": "syn",
			"example": "apprehension, catch, collar, pinch, taking into custody, check, halt, hitch, stay, stop, stoppage, nail, apprehend, pick up, nab, cop, turn back, contain, hold back, get, hold"
		}
	]
}