API v1 - Introduction
Linguin AI offers language detection as a service. Our API endpoints provide easy access to detect the language(s) of a text, bulk detection, and account status information.
Our API responds in JSON only. Payload must be provided as form data.
All requests have to made via https. Any text transmitted to us via API will be permanently deleted immediately after detection - including from any log files.
We offer a language binding for Ruby, Python, and Java. Bindings for JavaScript and Go are on their way. Please feel free to contribute to any of our libraries or build your own!
If you encounter a detection result you believe to be wrong, we would love to learn from you: Tell us about the wrong result here, we are reviewing every submission and use it to improve our service.
Authentication
To authenticate, use this code:
require 'linguin'
Linguin.api_key = "YOURAPIKEY"
from linguin import Linguin
linguin = Linguin("YOURAPIKEY")
# With shell, you can just pass the correct header with each request
curl https://api.linguin.ai/v1/detect \
-H "Authorization: Bearer YOURAPIKEY"
Make sure to replace
YOURAPIKEYwith your API key.
Linguin AI uses API Keys to allow access to the API.
You can sign up for your API Key here.
Linguin AI expects the API Key to be included in all API requests in a header that looks like the following:
Authorization: Bearer YOURAPIKEY
Language Detection
Single Detection
require 'linguin' # version 1.x
Linguin.api_key = "YOURAPIKEY"
response = Linguin.detect("What language might this be?")
# response is a Linguin::Response object:
response.success?
=> true or false
response.results
=> [ { lang: "en", confidence: 0.92 }, { lang: "de", confidence: 0.11 } ]
# If something went wrong:
response.error
=> { code: 429, message: "This request exceeded the maximum allowed..." }
# see the full ruby gem documentation at
# https://github.com/LinguinAI/linguin-ruby
from linguin import Linguin
linguin = Linguin("YOURAPIKEY")
response = linguin.detect("What language might this be?")
# response is a LinguinResponse object
response.is_success
# True
response.result
# {'results': [{ 'lang': 'en', confidence: 1.0 }, ...]}
# If something went wrong:
response.is_success
# False
print(response.error)
# Error code: 429. This request exceeded the maximum allowed...
# see the full python library documentation at
# https://github.com/LinguinAI/linguin-python
curl https://api.linguin.ai/v1/detect \
-H "Authorization: Bearer YOURAPIKEY" \
-d 'q=What language might this be?'
# The above command returns JSON structured like this:
{
"results": [
{ "lang": "en", "confidence": 0.92 },
{ "lang": "de", "confidence": 0.11 }
]
}
Use this endpoint to detect the language(s) of a single text.
HTTP Request
POST https://api.linguin.ai/v1/detect
Query Parameters
| Parameter | Description |
|---|---|
| q | The text you want to identify the language of. |
Bulk detection
require 'linguin' # version 1.x
Linguin.api_key = "YOURAPIKEY"
response = Linguin.detect(["What is this?", "Was ist das?"])
# response is a Linguin::BulkResponse object:
response.success?
=> true or false
# results are returned in the same order as requested
response.results
=> [
[{ lang: "en", confidence: 0.92 }, { lang: "de", confidence: 0.11 }],
[{ lang: "de", confidence: 0.87 }, { lang: "pl", confidence: 0.02 }]
]
# If something went wrong:
response.error
=> { code: 429, message: "This request exceeded the maximum allowed..." }
# see the full ruby gem documentation at
# https://github.com/LinguinAI/linguin-ruby
from linguin import Linguin
linguin = Linguin("YOURAPIKEY")
response = linguin.bulk(["What is this?", "Was ist das?"])
# response is a LinguinResponse object
response.is_success
# True
response.result
# {'results': [[{ 'lang': 'en', confidence: 1.0 }, ...], [{ 'lang': 'de', confidence: 1.0 }, ...]]}
# If something went wrong:
response.is_success
# False
print(response.error)
# Error code: 429. This request exceeded the maximum allowed...
# see the full python library documentation at
# https://github.com/LinguinAI/linguin-python
curl https://api.linguin.ai/v1/bulk \
-H "Authorization: Bearer YOURAPIKEY" \
-d 'q[]=What language might this be?' \
-d 'q[]=Welche Sprache ist das?'
# The above command returns JSON structured like this:
{
"results": [
[
{ "lang": "en", "confidence": 0.92 },
{ "lang": "de", "confidence": 0.11 }
],
[
{ "lang": "de", "confidence": 0.87 },
{ "lang": "pl", "confidence": 0.02 }
]
]
}
Use this endpoint to detect the language(s) of multiple texts.
If the total amount of detections would exceed your account limitations, an error is returned (no partial detections).
HTTP Request
POST https://api.linguin.ai/v1/bulk
URL Parameters
| Parameter | Description |
|---|---|
| q[] | Array of texts you want to identify the language of. |
Status
Account Status
require 'linguin'
Linguin.api_key = "YOURAPIKEY"
status = Linguin.status
# status is a Linguin::Status object:
status.detections_today
=> 198
status.daily_limit
=> 50_000 or nil
status.remaining_today
=> 49_802 or Float::INFINITY
# see the full ruby gem documentation at
# https://github.com/LinguinAI/linguin-ruby
from linguin import Linguin
linguin = Linguin("YOURAPIKEY")
response = linguin.status()
# response is a LinguinResponse object
response.result
# {'daily_limit': 50000, 'detections_today': 4500, 'remaining_today': 45500}
# for unlimited usage we return -1
curl https://api.linguin.ai/v1/status \
-H "Authorization: Bearer YOURAPIKEY"
# The above command returns JSON structured like this:
{
"status": {
"detections_today": 198,
"daily_limit": 50000, # or -1
"remaining_today": 49802 # or -1
}
}
Use this endpoint to check on the status of your account.
HTTP Request
GET https://api.linguin.ai/v1/status
Query Parameters
none
Languages
List of supported languages
require 'linguin'
languages = Linguin.languages
# languages is a hash:
languages
=> { ab: ["Abkhazian", "аҧсуа бызшәа, аҧсшәа"], ... }
# see the full ruby gem documentation at
# https://github.com/LinguinAI/linguin-ruby
from linguin import Linguin
languages = Linguin.languages()
# languages is a dictionary
languages
# { ab: ["Abkhazian", "аҧсуа бызшәа, аҧсшәа"], ... }
# see the full ruby gem documentation at
# https://github.com/LinguinAI/linguin-python
curl https://api.linguin.ai/v1/languages
# The above command returns JSON structured like this:
{
"ab": ["Abkhazian", "аҧсуа бызшәа, аҧсшәа"],
...
}
Use this endpoint to check on the status of your account.
HTTP Request
GET https://api.linguin.ai/v1/languages
Query Parameters
none
Errors
API calls may fail due to different reasons. Setting aside network related issues, like timeouts, here is how the Linguin API handles common cases:
We make use of HTTP status codes. A missing or invalid API Key will result in a 401 status code. If you exceed the limit of daily detection for your account - free accounts are limited to 100 detections per day, you may configure your own limit for paid accounts - the status code 429 will be returned.
Additionally, the body of the API response will contain a human readable message explaining what went wrong.
The Linguin API may return the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is missing or wrong. |
| 404 | Not Found -- The URL you tried to access doesn't exist. |
| 405 | Method Not Allowed -- Detection call have to be POST. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 429 | Too Many Requests -- You exceeded the daily detection limit of your account. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |