Languagelayer is a simple and powerful REST API built to efficiently match text of any length to its corresponding language, cross-referencing single words, expressions and grammatical constructions, as well as taking into account any existing accents, dialects and other linguistic deviations.
The languagelayer API relies on an ever-advancing, powerful and AI-based (Artificial Intelligence) detection algorithm, which increases in complexity and performance with each language detection API request performed. Only this way the languagelayer service can be capable of processing over 170 different languages & accents worldwide.
In spite of its complexity behind the curtains, our language detection API continuously manages to stand out due to its easy-to-use REST interface, simple JSON response format, quick response time and low bandwidth consumption.
After signing up, every user is assigned a personal API access key - a unique "password" used to make requests to the API.
To authenticate with the languagelayer API, simply attach your access_key to any endpoint URL:
http://api.languagelayer.com/detect?access_key=YOUR_ACCESS_KEY
Step 1: Choose endpoint URL
Language detection using the languagelayer API is simple. A standard (single) language detection API request is performed using the API's detect endpoint:
http://api.languagelayer.com/detect
Note: Looking to make batch (bulk) requests? Jump to Batch Requests »
Step 2: Required parameters
In order to make any API request, two required parameters must be specified - your personal access_key and the query text you would like the API to detect the language for.
| Parameter | Description |
|---|---|
| access_key | your personal password used to authenticate with the API - located in your Account Dashboard. |
| query | the full query text you would like the API to perform language detection for. |
Important: If your query text contains the special character &, please make sure to pass a URL encoded version of it into the API's query parameter. Read more »
Step 3: Optional parameters
| Parameter | Description | Default |
|---|---|---|
| show_query | set to "1" if you want the API's JSON result set to return your query text. | - |
| callback | append your preferred JSONP callback function name. (See "JSONP Callbacks" section) | - |
| format | set to "1" in order to request a prettified JSON result set (use only for debugging) | - |
Example Query:
The following query requests language detection for the famous english saying "The pessimist complains about the wind; the optimist expects it to change; the realist adjusts the sails."
http://api.languagelayer.com/detect ? access_key = YOUR_ACCESS_KEY & query = The%20pessimist%20complains%20about%20the%20wind%3B%20the%20optimist%20expects%20it%20to%20change%3B%20the%20realist%20adjusts%20the%20sails.
Strictly speaking, it is always a safer method to use standard URL encoding to encode your query text before passing it into the API's query parameter. However, URL encoding is required in case your query text contains the special character &.
Example text:
Find below an example text that is required to be URL encoded in order to be processed correctly.
I like apples & oranges.
Example query:
This is how the example text above has to be passed into the API's query parameter:
http://api.languagelayer.com/detect
? access_key = YOUR_ACCESS_KEY
& query = I%20like%20apples%20%26%20oranges.
[...]
Not sure about URL encoding? Have a look at this reference page »
All languagelayer API response data is returned in universal and lightweight JSON format. Find below a standard API result set:
{
"success": true,
"results": [
{
"language_code": "en",
"language_name": "English",
"probability": 83.896703655741,
"percentage": 100,
"reliable_result": true
}
]
}
API response objects:
Each API response consists of individual JSON response objects:
| Object | Description |
|---|---|
| "success" | Returns true or false depending on whether or not your API request was successful. |
| "results" | Returns a JSON array containing an object for each language matching your query text, starting with the most accurate match and descending from there. |
| "language_code" | Returns the 2-digit language code for the respective language. |
| "language_name" | Returns the language name for the respective language. |
| "probability" | Returns a numerical value based on the length of the provided query text and how well it is identified as a language. For reference only. |
| "percentage" | Returns a percentage value (0-100%) in order to put in perspective the API's confidence about the respective language match and present the confidence margin between multiple matches. |
| "reliable_result" | Returns true or false depending on whether or not the API is completely confident about the main match. |
Customers subscribed to the Basic Plan (and higher) may establish a secure connection (industry-standard SSL) to the languagelayer API and all data provided by and accessible through it.
To connect securely, simply attach an s to the HTTP Protocol. (resulting in https://)
Requests to the API are rate limited based on your current subscription plan:
| Subscription Plan | Rate Limit |
|---|---|
| Free | 20 Requests / Minute |
| Basic | 60 Requests / Minute |
| Professional | 60 Requests / Minute |
| Enterprise | 100 Requests / Minute |
Important: In order to ensure maximum API performance, we recommend Free, Basic and Professional Plan users to limit their usage to a maximum of 1 API request per second; and Enterprise Plan to a maximum of 5 API requests per second.
If your rate limit for a given minute has been exceeded, the API will return an error carrying the type rate_limit_reached. This error is listed in the API Error Codes section below.
If your query fails, the languagelayer API will return a 3-digit error-code, an internal error type and a plain text "info" object containing suggestions for the user.
Find below an example error - triggered when no query text was specified:
{
"success": false,
"error": {
"code": 210,
"type": "no_query_text_provided",
"info": "You have not specified a query text. [Required format: ...&query=my+query+text]"
}
}
| Type | Message | Description |
|---|---|---|
| 404 | "404_not_found" | User requested a resource which does not exist. |
| 101 | "missing_access_key" | User did not supply an Access Key. |
| 101 | "invalid_access_key" | User entered an invalid Access Key. |
| 103 | "invalid_api_function" | User requested a non-existent API endpoint or function. |
| 210 | "no_query_text_provided" | User did not provide a query text. |
| 104 | "usage_limit_reached" | User has reached or exceeded his Subscription Plan's monthly API Request Allowance. |
| 105 | "https_access_restricted" | The user's current Subscription Plan does not support HTTPS Encryption. |
| 106 | "rate_limit_reached" | User has exceeded the maximum allowed rate limitation and is referred to the "Rate Limits" section of the API Documentation. |
| 107 | "function_access_restricted" | User requested an API function or parameter which is not supported by the user's current subscription plan. |
| 102 | "inactive_user" | The user's account is not active. User will be prompted to get in touch with Customer Support. |
| 211 | "query_text_is_array" | User requested standard "detect" API endpoint but provided an array. |
| 212 | "query_text_no_array" | User requested "batch" detection API endpoint but did not provide a valid array. |
| 221 | "too_many_queries" | User requested "batch" detection API endpoint using too many "query[]" texts (Maximum: 100). |
| 910 | "detection_failed" | Our systems failed processing the language detection request. |
| 911 | "batch_detection_failed" | Our systems failed processing the batch language detection request. |
The languagelayer API also supports JSONP Callbacks. To use this feature, simply attach:
callback = CALLBACK_FUNCTION
to any API Endpoint, and the result set will be returned wrapped in the callback function you specified.
Example query:
http://api.languagelayer.com/detect ? access_key = YOUR_ACCESS_KEY & query = The%20pessimist%20complains%20about%20the%20wind%3B%20the%20optimist%20expects%20it%20to%20change%3B%20the%20realist%20adjusts%20the%20sails. & callback = CALLBACK_FUNCTION
Not sure about what JSONP does? Here's a helpful Stack Overflow thread.
Example response:
CALLBACK_FUNCTION ({
{
"success": true,
"results": [
{
"language_code": "en",
"language_name": "English",
"probability": 83.896703655741,
"percentage": 100,
"reliable_result": true
}
]
}
})
Note: The API also supports Access-Control (CORS) headers.
In order to enhance readability the languagelayer API features a built-in JSON format function, which displays the API's Response in typically JSON-structured format.
To enable this function, simply attach format=1 to any valid API request URL:
http://api.languagelayer.com/detect
? access_key = YOUR_ACCESS_KEY
[...]
& format = 1
Please be aware that enabling format increases the API response's file size and might cause parsing problems. It should be used for debugging purposes only.
Using the API's languages endpoint you may access a JSON list of all currently supported languages.
http://api.languagelayer.com/languages ? access_key = YOUR_ACCESS_KEY
A list of all supported languages is also available on the Supported Languages page.
Standard (single) language detection is performed using the languagelayer API's default detect endpoint, simply by passing your preferred query text into the API's query parameter.
Example query:
http://api.languagelayer.com/detect ? access_key = YOUR_ACCESS_KEY & query = The%20pessimist%20complains%20about%20the%20wind%3B%20the%20optimist%20expects%20it%20to%20change%3B%20the%20realist%20adjusts%20the%20sails.
Example response:
{
"success": true,
"results": [
{
"language_code": "en",
"language_name": "English",
"probability": 83.896703655741,
"percentage": 100,
"reliable_result": true
}
]
}
Please note: For best results please make sure to always URL encode the contents of the query parameter before passing it into the API request URL.
The languagelayer API also offers the capability to process multiple query texts in a single API request. To make use of this feature, simply include the API's batch endpoint and pass a series of query[] parameters into your API request URL.
The following API request contains three separate query texts at once:
Example query:
http://api.languagelayer.com/batch ? access_key = YOUR_ACCESS_KEY & query[] = Good%20afternoon,%20sir.%20How%20are%20you%20today? & query[] = Guten%20Tag%20mein%20Herr,%20wie%20geht%20es%20Ihnen? & query[] = Buenos%20días%20señor,%20cómo%20está%20hoy?
Important: This documentation is presenting API requests primarily using the HTTP GET method. Please note that when making batch requests we'd highly recommend sending all query[] parameters using POST instead.
Important: For batch requests a maximum of 100 different query[] parameters has been established.
Example response:
After executing this batch request, the API will return single or multiple language detection results for each requested query text, in the same order they were initially specified in the API request.
{
"success": true,
"results": [
[
{
"language_code": "en",
"language_name": "English",
"probability": 16.143360832262,
"percentage": 100,
"reliable_result": true
}
],
[
{
"language_code": "de",
"language_name": "German",
"probability": 23.045066185021,
"percentage": 100,
"reliable_result": false
}
],
[
{
"language_code": "es",
"language_name": "Spanish",
"probability": 14.560273752505,
"percentage": 100,
"reliable_result": false
},
{
"language_code": "pt",
"language_name": "Portuguese",
"probability": 13.98519485076,
"percentage": 96.05035652818,
"reliable_result": false
},
{
"language_code": "gl",
"language_name": "Galician",
"probability": 13.585199932687,
"percentage": 93.30319033562,
"reliable_result": false
}
]
]
}
Please note: Since batch detection requests combine multiple API requests into one, each requested query[] text will increment your API usage by one request.
Each language detection JSON result comes with a probability score containing a numerical value (no range) representing how well the listed language was identified based on the text provided. This value is also a key ingredient for the API's Reliable Result calculation.
[...]
"probability": 110.339873,
[...]
Please note: The more text passed into the API's query parameter, the more representative the probability value becomes.
The languagelayer API will also return a percentage JSON response object, aiming to reflect its confidence with the respective language match in a familiar and more understandable way.
[...]
"percentage": 100,
[...]
Please note: The percentage value also serves the purpose of indicating the confidence margin between different language matches.
Finally, the API will return a reliable_result object containing true or false depending on whether or not the API is completely confident about the main language match.
[...]
"reliable_result": true
Please note: The reliable_result decision is based on a variety of factors, including the length of the text, the use of language-specific words and expressions, the probability value, and more.
Important: While a positive (true) reliable_result guarantees the respective language to be a complete and reliable match, language detection results containing a negative (false) value can still be very accurate.
// set API Access Key $access_key = 'YOUR_ACCESS_KEY'; // set query text $query = 'Hello my friend, how are you today?'; // Initialize CURL: $ch = curl_init('http://api.languagelayer.com/detect?access_key='.$access_key.'&query='.$query.''); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Store the data: $json = curl_exec($ch); curl_close($ch); // Decode JSON response and store array: $detection_result = json_decode($json, true);
function languagelayer_batch($query_array) {
// set access key
$access_key = 'YOUR_ACCESS_KEY';
foreach($query_array as $value) { $fields_string .= 'query[]='.$value.'&'; }
rtrim($fields_string, '&');
// Initialize CURL:
$ch = curl_init('http://api.languagelayer.com/batch?access_key='.$access_key);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Store the data:
$json = curl_exec($ch);
curl_close($ch);
echo $json;
// Decode JSON response:
$detection_results = json_decode($json, true);
// Access and use your preferred validation result objects
return $detection_results;
}
// set query texts
$query_array = array('hey friend', 'hola amigo', 'hallo freund');
// store results array
$results_array = languagelayer_batch($query_array);
// set endpoint and your access key var access_key = 'YOUR_ACCESS_KEY'; var query = 'Hello my friend, how are you?'; // AJAX call $.ajax({ url: 'http://api.languagelayer.com/detect?access_key=' + access_key + '&query=' + encodeURIComponent(query), dataType: 'jsonp', success: function(json) { // Access and use your preferred validation result objects console.log(json.success); } });
Please note: In this example, the use of JSONP is entirely optional.
Any issues with API Integration? Be sure to take a look at our Frequently Asked Questions to see if your question has already been answered.
Still need something clarified? Please get in touch with our support team at [email protected].
Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.
An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.
Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.
| Plan Name | Monthly Price | Number of Calls | Overage Price per call | Overage | Total price |
|---|---|---|---|---|---|
| Basic | $4.99 | 50,000 | 0.00011976 | 10,000 | $6.19 |
| Professional | $19.99 | 500,000 | 0.000047976 | 100,000 | $24.79 |
| Enterprise | $39.99 | 2,000,000 | 0.000023994 | 400,000 | $49.59 |
Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.
When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.
You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.
In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.
If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.
You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.
Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.
| Standard Support | Platinum Support | |
|---|---|---|
| General review on the issue |  |
|
| Access to knowledge base articles | |
|
| Email support communication | |
|
| Regular products updates and fixes | |
|
| Dedicated account team |  |
|
| Priority Email Support with unlimited communication | |
|
| Priority bug and review updates | |
|
| Option for quarterly briefing call with product Management | |
|
| Features requests as priority roadmap input into product | |
|
Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.
Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.
Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.
Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.
Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.
Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.
Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!
|
|