Hablaa API Documentation (alpha)

General info

Implementation

Dictionary Translation API Hablaa provides free translations from and into more than 160 languages. It is based on REST (tutorial).
Therefore the programming language does not really matter. The only rule is that you must follow the principles of REST.
The API implementation on Hablaa is called "Hablaa Server" (hs).

Terms of Service
API is free to use, regarding indicated data source license. There is a limit of call that may be done from one IP in fixed period of time, to prevent from abuse. The limit is not strict, there is heuristics that guesses whether queries comes from robot or human. If there are too many queries or they look non-human – IP gets blocked. If you are a developer and such case happens: please contact us.

Hablaa attribution
By using our API we would like to ask you to add some information about Hablaa. Please add a link to the Hablaa website: http://hablaa.com (Text Hablaa Dictionary Translation API)

Share
If you are using the Hablaa API please let us know. We are also glad to support you in using it.

Access

Access to API functions on Hablaa is based on the web interface.
All text in URL (except text for the translation) must be in lowercase.
The URL query-string always starts from URL-section "/hs/". It must be encoded (reference).
The ending slash ("/") is important.
The site subdomains are limited. Every subdomain represents the site language code. To get all possible site domains (language codes which are used as subdomains on Hablaa) - use this URL http://hablaa.com/hs/languages/ - response parameter "site_language" (see description below).
The request to each API function must use the next structure (strict hierarchy): http://[subdomain].hablaa.com/hs/[function_name]/[function_parameters]/

Url-elements

[subdomain]:Site subdomain which is used to get data in specific language. The default site language on Hablaa is English. Therefore you mustn't point "eng"-subdomain.
/hs/:The module "Hablaa Server" which contains implementation of API functionality.
[function_name]:All possible functions pointed in "[function_name]" are described below in this document (+examples).
[function_parameters]:Different functions can have no any parameters or have few ones. They must be splitted by slash ("/"). If the function has no any parameters, then only one ending slash must be used.

Output

Currently Hablaa Server supports one output format - JSON.

Functions

All API functions are grouped by the HTTP Methods: GET, PUT, POST, DELETE. One of them must be set in request.
According to REST principles, each function returns only one of possible HTTP codes.

Functions-response-codes

GET-functions: 200(OK) or 404(Not Found).
PUT-functions: 200(OK) or 204(No Content) or 404(Not Found).
POST-functions: 201(Created) or 404(Not Found).
DELETE-functions: 200(OK) or 404(Not Found).

Methods

GET

Info:

If the number/order/type of parameters required by function is wrong, it will always return code 404(Not Found).
All return data has JSON-format.

Output:

If data exists: HTTP code 200(OK) and JSON-data.
If data doesn't exist: HTTP code 404(Not found).

Functions

GET (1): languages

Description

Request a list of all the languages offered.

Url-structure

http://[subdomain].hablaa.com/hs/languages/

Parameters-mandatory

No

Parameters-optional

[subdomain]: Site subdomain represents the site language. Default value is "eng".

Output

HTTP code 200(OK) and JSON array of languages.
The output data contains array of items.
Every item represents language data as associated array of items.
Structure of the associated array (key=>value):
- lang_code => Language code. (mandatory)
- site_language => "Site language"-marker ("0" - "no", "1" - "yes"). (mandatory)
- name => Language name. (mandatory)

The result is sorted by the language name, BUT the current site language will be always at the first place.

Examples
1. With subdomain
URL: http://deu.hablaa.com/hs/languages/
Description: Request for the site languages in German.
Response:
- HTTP code: 200(OK)
- Data:
[{"lang_code":"deu","site_language":"1","name":"Deutsch"},{"lang_code":"afr","site_language":"1","name":"Afrikaans"},{"lang_code":"ale","site_language":"0","name":"Aleutisch"},...]
- Data in readable format:
[
	{
		"lang_code":		"eng",
		"site_language":	"1",
		"name":			"English"
	},
	{
		"lang_code":		"afr",
		"site_language":	"1",
		"name":			"Afrikaans"
	},
	{
		"lang_code":		"ale",
		"site_language":	"0",
		"name":			"Aleut"
	},
	...
]
2. Without subdomain
URL: http://hablaa.com/hs/languages/
Description: Request for the site languages in German.
Response:
- HTTP code: 200(OK)
- Data:
[{"lang_code":"eng","site_language":"1","name":"English"},{"lang_code":"afr","site_language":"1","name":"Afrikaans"},{"lang_code":"ale","site_language":"0","name":"Aleut"},{"lang_code":"ara","site_language":"1","name":"Arabic"},{"lang_code":"ast","site_language":"0","name":"Asturian"},...]
- Data in readable format:
[
	{
		"lang_code":		"eng",
		"site_language":	"1",
		"name":			"English"
	},
	{
		"lang_code":		"afr",
		"site_language":	"1",
		"name":			"Afrikaans"
	},
	{
		"lang_code":		"ale",
		"site_language":	"0",
		"name":			"Aleut"
	},
	...
]

GET (2): translation

Description

Request a translation for a text.

Url-structure

http://[subdomain].hablaa.com/hs/translation/[text_to_translate]/[lang_code_src]-[lang_code_dst]/

Parameters-mandatory

[text_to_translate]: Text or word for translation.
[lang_code_src]: Source language code.
[lang_code_dst]: Target language code.

Parameters-optional

[subdomain]: Site subdomain represents the site language. Default value is "eng".

Output

1. Translation exists on Hablaa: the script will return HTTP code 200(OK) and JSON-data.
The output data contains array of items.
Every item represents possible translation of the requested text/word; represented as associated array of items.
Structure of the associated array (key=>value):
- text => Translated text; question mark ("?") must be replaced by "%3F". (mandatory)
- pos => Part Of Speech; associated array of items. (mandatory)
-- code => Code of POS.
-- title => Title of POS.
- transcription => Transcription of the text. (optional)
- source => The source from which the text was taken. (optional)
- source_link => Link to the source. (optional)
- description => Description of the text. (optional)
- addinfo => Array of items; every item represented as associated array. (optional)
-- code => Code of the additional info-item.
-- title => Title of the additional info-item.
2. Translation doesn't exist on Hablaa: the script will return empty page with HTTP code 404(Not found).

Examples
1. With subdomain
URL: http://deu.hablaa.com/hs/translation/apple/eng-deu/
Description: Request for the translation of word "apple" from English to German. Get response in German.
Response:
- HTTP code: 200(OK)
- Data:
[{"text":"Apfel","pos":{"code":"---","title":"---"},"source":"Jmdict, Jim Breen"},{"text":"Apfel","pos":{"code":"substantiv","title":"Substantiv"},"addinfo":[{"code":"{m}","title":"Maskulinum"}]}]
- Data in readable format:
[
	{
		"text":"Apfel",
		"pos":{
			"code":"---",
			"title":"---"
		},
		"source": "Jmdict, Jim Breen"
	},
	{
		"text":"Apfel",
		"pos":{
			"code":"substantiv",
			"title":"Substantiv"
		},
		"addinfo":[
			{
				"code":"{m}",
				"title":"Maskulinum"
			}
		]
	}
]
2. Without subdomain
URL: http://hablaa.com/hs/translation/apple/eng-deu/
Description: Request for the translation of word "apple" from English to German. Get response in English.
Response:
- HTTP code: 200(OK)
- Data:
[{"text":"Apfel","pos":{"code":"---","title":"---"},"source":"Jmdict, Jim Breen"},{"text":"Apfel","pos":{"code":"nn","title":"noun singular"},"addinfo":[{"code":"{m}","title":"Maskulinum"}]}]
- Data in readable format:
[
	{
		"text":"Apfel",
		"pos":{
			"code":"---",
			"title":"---"
		},
		"source":"Jmdict, Jim Breen"
	},
	{
		"text":"Apfel",
		"pos":{
			"code":"nn",
			"title":"noun singular"
		},
		"addinfo":[
			{
				"code":"{m}",
				"title":"Maskulinum"
			}
		]
	}
]

GET (3): translations-examples

Description

Request multiple example sentences (CACHED - for the fastest response)

Url-structure

http://hablaa.com/hs/translations-examples/[text_to_translate]/[lang_code_src]-[lang_code_dst]/

Parameters-mandatory

[text_to_translate]: Text or word for translation.
[lang_code_src]: Source language code.
[lang_code_dst]: Target language code.

Parameters-optional

No

Output

1. Translations exists on Hablaa: the script will return HTTP code 200(OK) and JSON-data.
The output data contains array of items.
Every item represents possible similar translation of the requested text/word; represented as associated array of items.
Structure of the associated array (key=>value):
- type => Associated array of src|dst texts ("src" - source, "dst" - destination/target). (mandatory)
2. Translations doesn't exist on Hablaa: the script will return empty page with HTTP code 404(Not found).

Examples
1. With or without subdomain (it doesn't matter)
URL: http://hablaa.com/hs/translations-examples/apple/eng-deu/
Description: Request for the example sentences which contain word "apple" from English to German.
Response:
- HTTP code: 200(OK)
- Data:
[{"src":"Madam President, the destruction is unprecedented: floods, hail and gales have destroyed considerable areas of apple orchards in the Pilion region.","dst":"Frau Pr\u00e4sidentin, die Katastrophe war von einem beispiellosen Ausma\u00df: \u00dcberschwemmungen, Hagel und St\u00fcrme haben weite Fl\u00e4chen mit Apfelkulturen in der Region Pilio zerst\u00f6rt."},{"src":"I will mention cotton, maize, and apple orchards, which were completely devastated.","dst":"Vollst\u00e4ndig vernichtet wurden die Baumwoll-, Mais-, und Apfelkulturen dieser Regionen."},{"src":"In relation to Parliament too - I venture to say - the decision to divide up urgency in the same way as a rotten apple is cut in two, offering us the good half, that is spending, actually increasing it as stated in the Funk report, and returning the bad half to the sender, that is revenue involving cuts for cereal farmers, does not seem to me a particularly edifying prospect.","dst":"Doch gestatten Sie mir zu sagen, verehrte Kollegen, da\u00df auch das Parlament in meinen Augen nicht gerade Ehre einlegt mit der Entscheidung, die Dringlichkeit wie einen wurmigen Apfel in zwei Teile zu zerschneiden und die gute H\u00e4lfte - die Ausgaben - f\u00fcr sich zu behalten oder gar zu erh\u00f6hen, wie der Bericht Funk vorschl\u00e4gt, w\u00e4hrend die andere H\u00e4lfte - n\u00e4mlich die Einnahmeseite mit den Abstrichen bei den Ackerkulturen, an den Absender zur\u00fcckgeschickt wird."},...]
- Data in readable format:
[
	{
		"src":"Madam President, the destruction is unprecedented: floods, hail and gales have destroyed considerable areas of apple orchards in the Pilion region.",
		"dst":"Frau Pr\u00e4sidentin, die Katastrophe war von einem beispiellosen Ausma\u00df: \u00dcberschwemmungen, Hagel und St\u00fcrme haben weite Fl\u00e4chen mit Apfelkulturen in der Region Pilio zerst\u00f6rt."
	},
	{
		"src":"I will mention cotton, maize, and apple orchards, which were completely devastated.",
		"dst":"Vollst\u00e4ndig vernichtet wurden die Baumwoll-, Mais-, und Apfelkulturen dieser Regionen."
	},
	{
		"src":"In relation to Parliament too - I venture to say - the decision to divide up urgency in the same way as a rotten apple is cut in two, offering us the good half, that is spending, actually increasing it as stated in the Funk report, and returning the bad half to the sender, that is revenue involving cuts for cereal farmers, does not seem to me a particularly edifying prospect.",
		"dst":"Doch gestatten Sie mir zu sagen, verehrte Kollegen, da\u00df auch das Parlament in meinen Augen nicht gerade Ehre einlegt mit der Entscheidung, die Dringlichkeit wie einen wurmigen Apfel in zwei Teile zu zerschneiden und die gute H\u00e4lfte - die Ausgaben - f\u00fcr sich zu behalten oder gar zu erh\u00f6hen, wie der Bericht Funk vorschl\u00e4gt, w\u00e4hrend die andere H\u00e4lfte - n\u00e4mlich die Einnahmeseite mit den Abstrichen bei den Ackerkulturen, an den Absender zur\u00fcckgeschickt wird."
	},
	...
]

GET (4): translations-similar

Description

Request multiple similar words/texts (CACHED - for the fastest response)

Url-structure

http://hablaa.com/hs/translations-similar/[text_to_translate]/[lang_code_src]-[lang_code_dst]/

Parameters-mandatory

[text_to_translate]: Text or word for translation.
[lang_code_src]: Source language code.
[lang_code_dst]: Target language code.

Parameters-optional

No

Output

1. Translations exists on Hablaa: the script will return HTTP code 200(OK) and JSON-data.
The output data contains array of items.
Every item represents possible similar translation of the requested text/word; represented as associated array of items.
Structure of the associated array (key=>value):
- type => Associated array of src|dst texts ("src" - source, "dst" - destination/target). (mandatory)
- text => Translated text (question mark must be replaced by "%3F"). (mandatory)
- transcription => Transcription of the text. (optional)
2. Translations doesn't exist on Hablaa: the script will return empty page with HTTP code 404(Not found).

Examples
1. With or without subdomain (it doesn't matter)
URL: http://deu.hablaa.com/hs/translations-similar/apple/eng-deu/
Description: Request for the similar translations of word "apple" from English to German.
Response:
- HTTP code: 200(OK)
- Data:
[{"src":{"text":"adam's apple"},"dst":{"text":"Adamsapfel"}},{"src":{"text":"apple blossom"},"dst":{"text":"Apfelbl\u00fcte"}},{"src":{"text":"apple butter"},"dst":{"text":"Apfelkraut"}},...]
- Data in readable format:
[
	{
		"src":{
			"text":"adam's apple"
		},
		"dst":{
			"text":"Adamsapfel"
		}
	},
	{
		"src":{
			"text":"apple blossom"
		},
		"dst":{
			"text":"Apfelbl\u00fcte"
		}
	},
	{
		"src":{
			"text":"apple butter"
		},
		"dst":{
			"text":"Apfelkraut"
		}
	},
	...
]

Contatti

Hablaa Translations
Opfikonerstrasse
8303 Bassersdorf
Zurich
Switzerland

Ordina traduzione

Traduzioni in Crowdsourcing di Altà Qualità a Grandi Prezzi

2011-2017 - Hablaa.com Dizionario Online | Traduzioni Italiano - Inglese