Getting Started
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:
URL-encoding your query text
Strictly speaking, it is always safer to use standard URL encoding to encode your query text before passing it to 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.
Example query:
This is how the example text above has to be passed into the API's query parameter:
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:
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
All Customers 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:
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. |
104 | "usage_limit_reached" | User has reached or exceeded his Subscription Plan's monthly API Request Allowance. |
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. |
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:
Not sure about what JSONP does? Here's a helpful Stack Overflow thread.
Example response:
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:
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.
A list of all supported languages is also available on the Supported Languages page.