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 using one of the following methods:

  • Bearer authorization header: Authorization: Bearer <your-api-key>
  • Basic access authentication username. Password can be empty or any value.

$ 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({
  key: '[INSERT YOUR KEY HERE]',
  //ssl: true|false (defaults to TRUE)
});
DetectLanguage.configure do |config|
  config.api_key = "YOUR API KEY"

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

detectlanguage.configuration.api_key = "YOUR API KEY"

# Enable secure mode (SSL) if you are passing sensitive data
# detectlanguage.configuration.secure = True
DetectLanguage.apiKey = "YOURAPIKEY";

// Enable secure mode (SSL) if passing sensitive information
// DetectLanguage.ssl = true;
DetectLanguage::setApiKey("YOUR API KEY");

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

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 = "I am a Teapot and a Submarine";

detectLanguage.detect(text, function(error, result) {
  console.log(JSON.stringify(result));
});

// result example

{
  data: {
    detections: [
      {
        language: "en",
        isReliable: true,
        confidence: 7.85
      }
    ]
  }
}
results = DetectLanguage.detect('Buenos dias señor')

# Result example

[{"language"=>"es", "isReliable"=>true, "confidence"=>6.62}]
result = detectlanguage.detect("Buenos dias señor")

# Result example

[{'isReliable': True, 'confidence': 12.04, 'language': 'es'}]
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);
$results = DetectLanguage::detect("Buenos dias señor");

# Result example

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

)

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 = [
  "I am a Teapot and a Submarine",
  "Soy una tetera y un submarino",
  "Jeg er en tekande og en ubåd"
];

detectLanguage.detect(texts, function(error, result) {
  console.log(JSON.stringify(result));
});

// Result example

{
  data: {
    detections: [
      [
        {
          language: "en",
          isReliable: true,
          confidence: 7.85
        }
      ],
      [
        {
          language: "es",
          isReliable: true,
          confidence: 3.75
        }
      ],
      [
        {
          language: "da",
          isReliable: true,
          confidence: 4.09
        }
      ]
    ]
  }
}
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}]]
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'} ] ]
String[] texts = {
  "Hello world",
  "Buenos dias señor"
};

List<List<Result>> results = DetectLanguage.detect(texts);
$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
                )

        )
)

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
$ 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.status(function(error, 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.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"}
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 = 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
)

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
languages = detectLanguage.languages(function(error, result) {
  console.log(JSON.stringify(result));
});

// Result example

[
  {
    code: "ab",
    name: "ABKHAZIAN"
  },
  {
    code: "aa",
    name: "AFAR"
  },
  {
    code: "af",
    name: "AFRIKAANS"
  }
  ...
]
languages = DetectLanguage.languages
languages = detectlanguage.languages()