SDE API with REST(Synonyms, Definitions and Examples)

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

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:

http://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 = "http://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. Log into our API Management to get your APIkey.

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')] }
}
	

Apply it Apply APIs right now