Documentation | Detect Language

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

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/v3/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");

import detectlanguage

detectlanguage.configuration.api_key = "YOUR API KEY"

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

DetectLanguage.configure do |config|
  config.api_key = 'YOUR API KEY'
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/v3/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
Score between 0 and 1

Score indicates detection accuracy. Higher score means higher confidence.

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

# Result example

[{"language":"en","score":0.9098}]

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

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

// result example

[{"language":"en","score":0.9955}]

$results = DetectLanguage::detect("Dolce far niente");

# Result example

Array
(
    [0] => stdClass Object
        (
            [language] => it
            [score] => 0.5074
        )

)

result = detectlanguage.detect("Dolce far niente")

# Result example

[{'language': 'it', 'score': 0.5074}]

detections, err := dl.Detect(context.TODO(), "Dolce far niente")

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, "Score:", detections[0].Score)

results = DetectLanguage.detect('Dolce far niente')

# Result example

[{"language" => "it", "score" => 0.5074}]

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

Result result = results.get(0);

System.out.println("Language: " + result.language);
System.out.println("Score: " + result.score);

DetectResult[] results = await client.DetectAsync("Dolce far niente");

Batch Detection

API endpoint: https://ws.detectlanguage.com/v3/detect-batch
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

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/v3/detect-batch \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-d "q[]=Hello+world" \
-d "q[]=Dolce+far+niente"

# Result example

[[{"language":"en","score":0.9098}],[{"language":"it","score":0.5074}]]

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

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

// Result example

[
  [
    {
      "language": "lt",
      "score": 0.8696
    }
  ],
  [
    {
      "language": "cs",
      "score": 0.3653
    },
    ...
  ]
]

$texts = array("Dolce far niente", "Hello world");
$results = DetectLanguage::detect($texts);

# Result example

Array
(
    [0] => Array
        (
            [0] => stdClass Object
                (
                    [language] => it
                    [score] => 0.5074
                )

        )

    [1] => Array
        (
            [0] => stdClass Object
                (
                    [language] => en
                    [score] => 0.9098
                )

        )

)

detectlanguage.detect_batch(["Dolce far niente", "Hello world"])

# Result example

[[{'language': 'it', 'score': 0.5074}], [{'language': 'en', 'score': 0.9098}]]

texts := []string{"labas rytas", "good morning"}
results, err := dl.DetectBatch(context.TODO(), 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_batch(['Dolce far niente', 'Labas rytas'])

# Result example

[[{"language" => "it", "score" => 0.5074}], [{"language" => "lt", "score" => 0.3063}]]

String[] texts = {
  "Dolce far niente",
  "Hello world"
};

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/v3/account/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)

curl https://ws.detectlanguage.com/v3/account/status  \
-H "Authorization: Bearer <YOUR_API_KEY>"

# Result example

{"date":"2018-04-07","requests":1510,"bytes":19843,"plan":"","plan_expires":null,"daily_requests_limit":0,"daily_bytes_limit":0,"status":"ACTIVE"}

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

// Result example

{
  date: "2015-02-21",
  requests: 31,
  bytes: 429,
  plan: "FREE",
  plan_expires: null,
  daily_requests_limit: 5000,
  daily_bytes_limit: 1048576,
  status: "ACTIVE"
}

$result = DetectLanguage::getStatus();

// Result example

stdClass Object
(
    [date] => 2013-10-19
    [requests] => 1680
    [bytes] => 21800
    [plan] => FREE
    [plan_expires] =>
    [daily_requests_limit] => 5000
    [daily_bytes_limit] => 1048576
    [status] => ACTIVE
)

result = detectlanguage.account_status()

# Result example

{ 'status': 'ACTIVE', 'daily_requests_limit': 5000, 'daily_bytes_limit': 1048576,
  'bytes': 3151, 'plan': 'FREE', 'date': '2014-03-29', 'requests': 263,
  'plan_expires': None }

result, err := dl.AccountStatus(context.TODO())

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

fmt.Fprintln(os.Stdout, "Status:", result.Status)
fmt.Fprintln(os.Stdout, "Requests sent today:", result.Requests)
fmt.Fprintln(os.Stdout, "Bytes sent today:", result.Bytes)
fmt.Fprintln(os.Stdout, "Plan:", result.Plan)
fmt.Fprintln(os.Stdout, "Plan expires:", result.PlanExpires)
fmt.Fprintln(os.Stdout, "Daily requests limit:", result.DailyRequestsLimit)
fmt.Fprintln(os.Stdout, "Daily bytes limit:", result.DailyBytesLimit)
fmt.Fprintln(os.Stdout, "Date:", result.Date)

result = DetectLanguage.account_status

# Result example

{"date"=>"2013-11-17", "requests"=>95, "bytes"=>2223, "plan"=>"FREE", "plan_expires"=>nil,
 "daily_requests_limit"=>5000, "daily_bytes_limit"=>1048576, "status"=>"ACTIVE"}

AccountStatusResponse accountStatus = DetectLanguage.getAccountStatus();

AccountStatus accountStatus = await client.GetAccountStatusAsync();

Languages List

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

Languages endpoint returns array of all supported languages.

Result

code - language code
name - language name

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

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

// Result example

[
  {
    "code": "aa",
    "name": "Afar"
  },
  {
    "code": "ab",
    "name": "Abkhazian"
  },
  ...
]

$results = DetectLanguage::getLanguages();

# Results example

Array
(
    [0] => stdClass Object
        (
            [code] => aa
            [name] => Afar
        )

    [1] => stdClass Object
        (
            [code] => ab
            [name] => Abkhazian
        )
    ...

languages = detectlanguage.languages()

# Result example

[{'code': 'aa', 'name': 'Afar'}, {'code': 'ab', 'name': 'Abkhazian'}, ...]

languages, err := dl.Languages(context.TODO())

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

LanguageInfo[] languages = DetectLanguage.getLanguages();

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