Documentation | Detect Language API

Introduction

We recommend using one of our official API clients:

If your programming language / framework is not supported, you can use API directly.

API returns results in JSON format.

Accepted request formats:

application/json
application/x-www-form-urlencoded

Security

Texts submitted to the API are used by language detection engine only. Texts are not stored or used in any other way.

If you are passing sensitive information to the API, make sure to use HTTPS protocol to secure network transfer.

Authentication

To use API you have to sign up and get your own API key.

When making a request to the API, you must pass API key in the authorization header:
Authorization: Bearer <your-api-key>

curl https://ws.detectlanguage.com/0.2/detect \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d q=Hello+world

var DetectLanguage = require('detectlanguage');

var detectlanguage = new DetectLanguage('YOUR API KEY');

DetectLanguage::setApiKey("YOUR API KEY");

// Enable secure mode if passing sensitive information
// DetectLanguage::setSecure(true);

import detectlanguage

detectlanguage.configuration.api_key = "YOUR API KEY"

# Enable secure mode (SSL) if you are passing sensitive data
# detectlanguage.configuration.secure = True

client := detectlanguage.New("YOUR API KEY")

DetectLanguage.configure do |config|
  config.api_key = "YOUR API KEY"

  # enable secure mode (SSL) if you are passing sensitive data
  # config.secure = true
end

DetectLanguage.apiKey = "YOURAPIKEY";

// Enable secure mode (SSL) if passing sensitive information
// DetectLanguage.ssl = true;

using DetectLanguage;

DetectLanguageClient client = new DetectLanguageClient("YOUR API KEY");

Single Detection

API endpoint: https://ws.detectlanguage.com/0.2/detect
HTTP method: POST

Request parameters

q - text, mandatory (must be valid UTF-8 encoded string)

Response format

Response contains array of language candidates.

Each result contains following values:

Language code
Confidence score
Is reliable - true/false

Confidence value depends on how much text you pass and how well it is identified. The more text you pass, the higher confidence value will be. It is not a range, it can be higher than 100.

Reliability is not directly linked to the confidence. In case your text contains words in different languages then isReliable: true would identify that first detected language is significantly more probable than the second one. When only one language is detected isReliable: false would mean that confidence is very low.

curl https://ws.detectlanguage.com/0.2/detect \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d q=Hello+world

# Result example

{"data":{"detections":[{"language":"en","isReliable":true,"confidence":11.94}]}}

var text = "Hello! How are you?";

detectlanguage.detect(text).then(function(result) {
  console.log(JSON.stringify(result));
});

// result example

[
  {
    "language": "en",
    "isReliable": true,
    "confidence": 18.2
  }
]

$results = DetectLanguage::detect("Buenos dias señor");

# Result example

Array
(
    [0] => stdClass Object
        (
            [language] => es
            [isReliable] => 1
            [confidence] => 10.24
        )

)

result = detectlanguage.detect("Buenos dias señor")

# Result example

[{'isReliable': True, 'confidence': 12.04, 'language': 'es'}]

detections, err := client.Detect("Buenos dias señor")

if err != nil {
    fmt.Fprintln(os.Stderr, "error detecting language:", err)
    os.Exit(1)
    return
}

fmt.Fprintln(os.Stdout, "Language:", detections[0].Language)
fmt.Fprintln(os.Stdout, "Reliable:", detections[0].Reliable)
fmt.Fprintln(os.Stdout, "Confidence:", detections[0].Confidence)

results = DetectLanguage.detect('Buenos dias señor')

# Result example

[{"language"=>"es", "isReliable"=>true, "confidence"=>6.62}]

List<Result> results = DetectLanguage.detect("Hello world");

Result result = results.get(0);

System.out.println("Language: " + result.language);
System.out.println("Is reliable: " + result.isReliable);
System.out.println("Confidence: " + result.confidence);

DetectResult[] results = await client.DetectAsync("Buenos dias señor");

Batch Detection

API endpoint: https://ws.detectlanguage.com/0.2/detect
HTTP method: POST

Batch mode allows to detect language of several texts using one query. It saves network bandwidth and significantly increases performance.

Request parameters

q - array of texts, mandatory (must be valid UTF-8 encoded strings)

Response format

Response contains array of language candidates.

Note: batch detections are counted as separate requests, i.e. if 3 texts were passed they will be counted as 3 separate requests.

curl https://ws.detectlanguage.com/0.2/detect \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d "q[]=Hello+world" \
-d "q[]=Buenos+dias"

# Result example

{"data":{"detections":[[{"language":"en","isReliable":true,"confidence":11.94}],[{"language":"es","isReliable":true,"confidence":9.38}]]}}

var texts = ['šešios žąsys', 'Strč prst skrz krk'];

detectlanguage.detect(texts).then(function(result) {
  console.log(JSON.stringify(result));
});

// Result example

[
  [
    {
      "language": "lt",
      "isReliable": true,
      "confidence": 5.5
    }
  ],
  [
    {
      "language": "cs",
      "isReliable": true,
      "confidence": 3.645
    },
    ...
  ]
]

$texts = array("Buenos dias señor", "Hello world");
$results = DetectLanguage::detect($texts);

# Result example

Array
(
    [0] => Array
        (
            [0] => stdClass Object
                (
                    [language] => es
                    [isReliable] => 1
                    [confidence] => 10.24
                )

        )

    [1] => Array
        (
            [0] => stdClass Object
                (
                    [language] => en
                    [isReliable] => 1
                    [confidence] => 11.94
                )

        )
)

result = detectlanguage.detect(["Buenos dias señor", "Labas rytas"])

# Result example

[ [ {'isReliable': True, 'confidence': 12.04, 'language': 'es'} ],
  [ {'isReliable': True, 'confidence': 9.38, 'language': 'lt'} ] ]

texts := []string{"labas rytas", "good morning"}
results, err := client.DetectBatch(texts)

if err != nil {
    fmt.Fprintln(os.Stderr, "error detecting language:", err)
    os.Exit(1)
    return
}

fmt.Fprintln(os.Stdout, "First text language:", detections[0][0].Language)
fmt.Fprintln(os.Stdout, "Second text language:", detections[1][0].Language)

results = DetectLanguage.detect(["Buenos dias señor", "Labas rytas"])

# Result example

[[{"language"=>"es", "isReliable"=>true, "confidence"=>6.62}], [{"language"=>"lt", "isReliable"=>true, "confidence"=>6.82}]]

String[] texts = {
  "Hello world",
  "Buenos dias señor"
};

List<List<Result>> results = DetectLanguage.detect(texts);

string[] texts = {"labas rytas", "good morning"};

DetectResult[][] results = await client.BatchDetectAsync(texts);

Account Status

API endpoint: https://ws.detectlanguage.com/0.2/user/status
HTTP method: GET

Response

date - today's date (UTC timezone)
requests - requests sent today
bytes - text bytes sent today
plan - plan code
plan_expires - plan expiration date
daily_requests_limit - requests limit per day
daily_bytes_limit - bytes limit per day
status - account status (ACTIVE or SUSPENDED)

Languages List

API endpoint: https://ws.detectlanguage.com/0.2/languages
HTTP method: GET

Languages endpoint returns array of all supported languages.

Result

code - language code
name - language name

curl https://ws.detectlanguage.com/0.2/languages

detectlanguage.languages().then(function(result) {
  console.log(JSON.stringify(result));
});

// Result example

[
  {
    code: "aa",
    name: "AFAR"
  },
  {
    code: "ab",
    name: "ABKHAZIAN"
  },
  {
    code: "af",
    name: "AFRIKAANS"
  }
  ...
]

languages = detectlanguage.languages()

languages, err := client.Languages()

if err != nil {
    fmt.Fprintln(os.Stderr, "error getting languages list:", err)
    os.Exit(1)
    return
}

fmt.Fprintln(os.Stdout, "Supported languages:", len(languages))
fmt.Fprintln(os.Stdout, "First language code:", languages[0].Code)
fmt.Fprintln(os.Stdout, "First language name:", languages[0].Name)

languages = DetectLanguage.languages

Language[] languages = await client.GetLanguagesAsync();