# Detect language API

`detect_language` takes a text and returns a list of the most likely languages.

It is built on top of the open-source [Compact Language Detector 2 (CLD2)](https://github.com/CLD2Owners/cld2) library.

**Command name:** `detect_language`\
**Success status:** `200 OK`

### On this page

* [Common parameters](#common-parameters)
* [Parameters](#parameters)
* [Behavior notes](#behavior-notes)
* [Response schema](#response-schema)
* [Request examples](#request-examples)
* [Errors](#errors)

**Related**: [Overview](/v6.10.0.0/api-reference/overview.md), [Supported languages](/v6.10.0.0/features/supported-languages.md), [Why WProofreader auto detect language doesn't work for small piece of texts?](/v6.10.0.0/faq/technical/languages/why-wproofreader-auto-detect-language-doesnt-work-for-small-piece-of-texts.md)

### Common parameters

`cmd` selects the command to run.

| Name  | Type   | Required | Description                |
| ----- | ------ | -------- | -------------------------- |
| `cmd` | string | Yes      | Must be `detect_language`. |

These parameters work with any `cmd`.

| Name        | Type   | Required   | Description                                                       |
| ----------- | ------ | ---------- | ----------------------------------------------------------------- |
| `serviceid` | string | Cloud only | Cloud API key. Required for Cloud requests. Not used on-premises. |
| `format`    | string | No         | Response format. Supported: `json` (default), `xml`.              |
| `callback`  | string | No         | JSONP wrapper function name. Use only with `format=json`.         |

See [Overview](/v6.10.0.0/api-reference/overview.md#common-parameters) for details.

### Parameters

These are parameters specific to `cmd=detect_language`.

{% hint style="warning" %}
`detect_language` does **not** support `short_answer`.
{% endhint %}

| Name     | Type   | Required | Description                                                            |
| -------- | ------ | -------- | ---------------------------------------------------------------------- |
| `text`   | string | Yes      | Text to detect the language for.                                       |
| `locale` | string | No       | Localization for `LangName`. Accepted formats: `es`, `es-ES`, `es_ES`. |

### Behavior notes

* `locale` affects only `LangName`. It does not affect detection.
* If the language cannot be detected, you still get `200 OK`.
  * The response contains a single item with `LangShortCode=Unknown`.
* For better accuracy on long texts, split content into sentences.
  * Run `detect_language` per sentence.
* At least 3 words in text is needed to detected the language. See the information [here](/faq/technical/languages/why-wproofreader-auto-detect-language-doesnt-work-for-small-piece-of-texts.md).

### Response schema

The response contains language candidates.

Use `format` to switch between JSON and XML.

{% tabs %}
{% tab title="JSON" %}

```json
[
  {
    "LangShortCode": "en_US",
    "LangName": "English (US)",
    "Proportion": 0.98
  }
]
```

{% endtab %}

{% tab title="XML" %}

```xml
<LanguageDetection>
  <Language>
    <LangShortCode>en_US</LangShortCode>
    <LangName>English (US)</LangName>
    <Proportion>0.98</Proportion>
  </Language>
</LanguageDetection>
```

{% endtab %}
{% endtabs %}

* `LangShortCode` (string)\
  Detected language code. See [Supported languages](/v6.10.0.0/features/supported-languages.md). Can also be `Unknown`.
* `LangName` (string)\
  Human-readable language name. Localized using `locale` when provided.
* `Proportion` (number)\
  Confidence / proportion of this language in the text. Higher means “more likely”.

### Request examples

#### Example: single language detected

Request:

{% tabs %}
{% tab title="GET" %}

```http
GET https://endpoint/api?cmd=detect_language&text=this%20sampl%20text%20demonstrates%20the%20work%20of%20the%20Web%20API%20service.
```

{% endtab %}

{% tab title="POST" %}

```http
POST https://endpoint/api
Content-Type: application/json

{
  "cmd": "detect_language",
  "text": "this sampl text demonstrates the work of the Web API service."
}
```

{% endtab %}
{% endtabs %}

Response (`200 OK`):

{% tabs %}
{% tab title="JSON" %}

```json
[
  {
    "LangShortCode": "en_US",
    "LangName": "English (US)",
    "Proportion": 0.98
  }
]
```

{% endtab %}

{% tab title="XML" %}

```xml
<LanguageDetection>
  <Language>
    <LangShortCode>en_US</LangShortCode>
    <LangName>English (US)</LangName>
    <Proportion>0.98</Proportion>
  </Language>
</LanguageDetection>
```

{% endtab %}
{% endtabs %}

#### Example: localized language name (`locale=es-ES`)

Request:

{% tabs %}
{% tab title="GET" %}

```http
GET https://endpoint/api?cmd=detect_language&locale=es-ES&text=this%20sampl%20text%20demonstrates%20the%20work%20of%20the%20Web%20API%20service.
```

{% endtab %}

{% tab title="POST" %}

```http
POST https://endpoint/api
Content-Type: application/json

{
  "cmd": "detect_language",
  "locale": "es-ES",
  "text": "this sampl text demonstrates the work of the Web API service."
}
```

{% endtab %}
{% endtabs %}

Response (`200 OK`):

{% tabs %}
{% tab title="JSON" %}

```json
[
  {
    "LangShortCode": "en_US",
    "LangName": "Inglés (Estados Unidos)",
    "Proportion": 0.98
  }
]
```

{% endtab %}

{% tab title="XML" %}

```xml
<LanguageDetection>
  <Language>
    <LangShortCode>en_US</LangShortCode>
    <LangName>Inglés (Estados Unidos)</LangName>
    <Proportion>0.98</Proportion>
  </Language>
</LanguageDetection>
```

{% endtab %}
{% endtabs %}

#### Example: no language detected

Request:

{% tabs %}
{% tab title="GET" %}

```http
GET https://endpoint/api?cmd=detect_language&text=asdfghjkl
```

{% endtab %}

{% tab title="POST" %}

```http
POST https://endpoint/api
Content-Type: application/json

{
  "cmd": "detect_language",
  "text": "asdfghjkl"
}
```

{% endtab %}
{% endtabs %}

Response (`200 OK`):

{% tabs %}
{% tab title="JSON (default)" %}

```json
[
  {
    "LangShortCode": "Unknown",
    "LangName": "Unknown",
    "Proportion": 0.0
  }
]
```

{% endtab %}

{% tab title="XML" %}

```xml
<LanguageDetection>
  <Language>
    <LangShortCode>Unknown</LangShortCode>
    <LangName>Unknown</LangName>
    <Proportion>0</Proportion>
  </Language>
</LanguageDetection>
```

{% endtab %}
{% endtabs %}

### Errors

This command has no command-specific `4xx` errors.

When language detection fails, the response is still `200 OK` with `LangShortCode=Unknown`.

Common API errors (for example an invalid `serviceid`) use the shared error format from [Overview](/v6.10.0.0/api-reference/overview.md#errors).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wproofreader.com/api-reference/detect-language-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.