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: 

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)
curl https://ws.detectlanguage.com/0.2/user/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.userStatus().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.user_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 := client.UserStatus()

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.user_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"}

UserStatus userStatus = await client.GetUserStatusAsync();

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();