NAV
shell ruby python

API v2 - Introduction

Linguin AI offers language and profanity detection as a service. Profanity detection only works for english as of now. Our API endpoints provide easy access to detect the language(s) of a text or the likelihood of it containing profanity, including bulk detection, and account status information.

Our API responds in JSON only. Payload must be provided as JSON or 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/v2/detect/language \
  -H "Authorization: Bearer YOURAPIKEY"

Make sure to replace YOURAPIKEY with 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 Language Detection

require 'linguin' # version 2.x

Linguin.api_key = "YOURAPIKEY"

response = Linguin.detect_language("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_language("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/v2/detect/language \
  -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/v2/detect/language

Query Parameters

Content-Type Body
JSON { "q": "text to analyze" }
form data q=text+to+analyze

Bulk Language Detection

require 'linguin' # version 2.x

Linguin.api_key = "YOURAPIKEY"

response = Linguin.detect_language(["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_detect_language(["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/v2/bulk_detect/language \
  -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/v2/bulk_detect/language

Query Parameters

Content-Type Body
JSON { "q": ["sentence number one", "Noch ein Satz"] }
form data q[]=text+one&q[]=text+two

Profanity Detection

Single Profanity Detection

require 'linguin' # version 2.x

Linguin.api_key = "YOURAPIKEY"

response = Linguin.detect_profanity("You are a moron!")

# response is a Linguin::Response object:
response.success?
=> true or false

response.score
=> 0.9981

# 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_profanity("You are a moron!")

# response is a LinguinResponse object
response.is_success
# True

response.result
# {'score': 0.9981}

# 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/v2/detect/profanity \
  -H "Authorization: Bearer YOURAPIKEY" \
  -d 'q=You are a moron!'

# The above command returns JSON structured like this:
{
  "score": 0.9981
}

Use this endpoint to detect the profanity in a single text.

HTTP Request

POST https://api.linguin.ai/v2/detect/profanity

Query Parameters

Content-Type Body
JSON { "q": "text to analyze" }
form data q=text+to+analyze

Bulk Profanity Detection

require 'linguin' # version 2.x

Linguin.api_key = "YOURAPIKEY"

response = Linguin.detect_profanity(["You are a moron!", "That was not a nice comment."])

# response is a Linguin::BulkResponse object:
response.success?
=> true or false

# results are returned in the same order as requested
response.scores
=> [0.9981, 0.0315]

# 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_detect_profanity(["What is this?", "Was ist das?"])

# response is a LinguinResponse object
response.is_success
# True

response.result
# {'scores': [0.9981, 0.0315]}

# 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/v2/bulk_detect/profanity \
  -H "Authorization: Bearer YOURAPIKEY" \
  -d 'q[]=You are a moron!' \
  -d 'q[]=That was not a nice comment.'

# The above command returns JSON structured like this:
{
  "scores": [
    0.9981,
    0.0315
  ]
}

Use this endpoint to detect profanity in 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/v2/bulk_detect/profanity

Query Parameters

Content-Type Body
JSON { "q": ["sentence number one", "another sentence"] }
form data q[]=text+one&q[]=text+two

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/v2/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/v2/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/v2/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/v2/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.
shell ruby python