Extraction API with REST (Tooltip)

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

This document explains common features of Extraction API using the RESTful style.

What is the tooltip?

Please, click any word or drag any words then you can understand easily.

Introduction

Extraction API is one of vocaDB Dictionary APIs and provides extracted words and idioms list results by user's English level from searched text/sentence input.

What is the difference between dictionary APIs and Extraction API?
Extraction API services sentence search. Dictionary APIs service four input types such as a word, idiom, non-English word and sentence(s).


Working with results

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_text.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 text string
Use the q query parameter to identify the string to extract or search.
User's Level
Use the level query parameter to get the word and idiom list from input word by user's English level.
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( 
	"slang" => 'en', 
	"tlang"=> 'ko',
	"q"=> 'Valuable clients can read and learn translated docs with audio anytime, anywhere.', 
	"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 = Simple_word_API_path;
}
else
{
	$link = Extraction_text_API_path;
}
$ch = curl_init( $link );
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:

JSON (Text)

{
	"type": 4
	"contents": {
		"trans": {
			"count": 4,  /* Inputed total words */
			"letters": 27
		},
		"words": {
			"relative_words": [
			{
				"voca": "crisis",
				"ilevel": "23",
				"part": "명",
				"means": "1. 위기 2. 중대 국면, 고비 (=crises)",
				"level": "중3",
				"audio": "crisis",
				"origin": "crisis"
			},
			{
				"voca": "financial",
				"ilevel": "23",
				"part": "형",
				"means": "재정의, 자금의",
				"level": "중3",
				"audio": "financial",
				"origin": "financial"
			}
			]
		}
		"newwords": 0,
		"idioms": {
			"relative_idioms": [
			{
				"idiom": "financial crisis",
				"ilevel": "23",
				"level": "중3",
				"means": "금융 위기",
				"audio": "financial crisis",
				"origin": "financial crisis"
			}
			]
			}
		}
}

Query parameter reference

All required parameters for Extraction 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 words & sentence(s) The text to be searched or extracted word list. 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 }
d
  • 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.

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.

Sample API

Cases Example Value Comments
sentence(s) The financial crisis is considered by many economists to be the worst financial crisis English limit 500 letters
depend on the price

Result Value of API

Returned JSON format : 

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

Apply it Apply for APIs right now