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://apilayer.net/api/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://apilayer.net/api/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://apilayer.net/api/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://apilayer.net/api/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 60 Requests / Minute
Basic 60 Requests / Minute
Professional 60 Requests / Minute
Enterprise 300 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://apilayer.net/api/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://apilayer.net/api/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://apilayer.net/api/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://apilayer.net/api/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://apilayer.net/api/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://apilayer.net/api/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://apilayer.net/api/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://apilayer.net/api/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 support@apilayer.com.