API Documentation

languagelayer API

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.


Specs & Overview

API Access Key & Authentication

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  
                

Get your free API Access Key


3-Step Quickstart Guide

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.   
                


URL encoding your query text


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 »


API Response

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.


256-bit HTTPS Encryption
Basic Pro Enterprise

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://)


Rate Limits

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.


API Error Codes

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]"    
  }
}
                


Common API errors:


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.

show all errors


JSONP Callbacks

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.


JSON Formatting

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.


Supported Languages

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.


API Features

Standard Detection
Free Basic Pro Enterprise

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.


Batch Detection
Basic Pro Enterprise

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:

  • Good afternoon, sir. How are you today? (English)
  • Guten Tag mein Herr, wie geht es Ihnen? (German)
  • Buenos días señor, cómo está hoy? (Spanish)

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.


Probability
Free Basic Pro Enterprise

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.


Percentage
Free Basic Pro Enterprise

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.


Reliable Result
Free Basic Pro Enterprise

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.


Code Examples

PHP

Standard language detection in PHP (GET):

// 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);
                

Batch language detection in PHP (POST):

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);
                

JavaScript (jQuery.ajax)

Standard language detection (GET):

// 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.


Help / Support


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].


Business Continuity - API Overages

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.

What is an overage?

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.0001497 10,000 $6.49
Professional $19.99 500,000 0.00005997 100,000 $25.99
Enterprise $39.99 2,000,000 0.0000299925 400,000 $51.99

Why does APILayer have overage fees?

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.

How do I know if I will be charged for overages?

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.

How will I be charged for my API subscription?

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.

What happens if I don’t have any overage fees?

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.

What if I consistently have more API calls than my plan allows?

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.

I would like to upgrade my plan. How can I do that?

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.


Introducing Platinum Support - Enterprise-grade support for APILayer

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.

What does Platinum Support include?

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!