Simple word API with REST (Tooltip)

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

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

What is the tooltip?

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

Introduction

The Simple API has two kinds: word and text API for search word.
If a searched word has no space, it is called Simple word API not Simple text API.

What is the difference between dictionary API and Simple word API?
Simple word API has simplified result from vocaDB on searched word.
The results are meaning, level, image and part of speech.
User can understand word's meaning easily by using pop up windows on mobile or PC.


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:

Simple word
https://vocabdb.com/v2_dic/api_dic_tooltip_word.php

Three query parameters are required with each search request:

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.
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"=> 'arrest', 
	"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 = LINK_Simple_TEXT;
}
else
{
	$link = LINK_Simple_WORD;
}
$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:

input : "insist", source language(slang) = en, target language(tlang) = ko

{
	"type": 1,
	"contents": {
		"voca": "insist",
		"part": "동",
		"level": "중3",
		"means": "1. 주장하다 2. 강조하다",
		"image": "89652"
	}
}

Query parameter reference

All required parameters for Simple 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 }
d
  • Direction or Device
 { 0 | 1 } Landscape or PC : 0
Portrait or Mobile : 1

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

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 input

Cases Example Value Comments
a word arrest English Search word
a word (not English) 성공, 逮捕 search word must have English word. No Result

Result Value of API

Returned JSON format : 

 { 
	"type": {-1 | 0 | 1 | 2 | 3 | 4} ,
	"contents": { 0 | -1 | -2 | -3 | word}
 }
 
	"word" = { voca, means, part, level, image }

Apply it Apply for APIs right now