Skip to main content

Language Detection API

The language detection endpoint identifies the language of a given text and returns a confidence score. This is useful for routing text into language-specific processing pipelines before calling other Sapling APIs.

Beyond the top prediction, the endpoint can return the runner-up candidates with their confidences, and — for mixed-language text — a per-segment breakdown showing which sentences are in which language. Every result also says whether the detection is reliable enough to act on, and which writing script the text is in. Over 170 languages are supported.

Try it out

Sample Code​

curl -X POST https://api.sapling.ai/api/v1/langdetect \
     -H "Content-Type: application/json" \
     -d '{"key":"<api-key>", "text":"This is an English sentence. Esta es una oración en español.", "segments": true}'

Sample Response​

{
    "lang": "en",
    "name": "English",
    "conf": 0.63,
    "reliable": false,
    "script": "Latn",
    "candidates": [
        {"lang": "en", "name": "English", "conf": 0.63},
        {"lang": "es", "name": "Spanish", "conf": 0.35},
        {"lang": "pt", "name": "Portuguese", "conf": 0.01}
    ],
    "segments": [
        {
            "start": 0,
            "end": 28,
            "text": "This is an English sentence.",
            "lang": "en",
            "name": "English",
            "conf": 0.98,
            "reliable": true,
            "script": "Latn",
            "candidates": [
                {"lang": "en", "name": "English", "conf": 0.98},
                {"lang": "sco", "name": "Scots", "conf": 0.01},
                {"lang": "nl", "name": "Dutch", "conf": 0.00}
            ]
        },
        {
            "start": 29,
            "end": 60,
            "text": "Esta es una oración en español.",
            "lang": "es",
            "name": "Spanish",
            "conf": 0.99,
            "reliable": true,
            "script": "Latn",
            "candidates": [
                {"lang": "es", "name": "Spanish", "conf": 0.99},
                {"lang": "gl", "name": "Galician", "conf": 0.00},
                {"lang": "pt", "name": "Portuguese", "conf": 0.00}
            ]
        }
    ]
}

Without segments, the response contains only lang, name, conf, reliable, script and candidates. Here the whole text is split between two languages, so its confidence is low and reliable is false, while each segment on its own is reliable.

Batch Requests​

To detect the language of many short texts — user messages to route, form submissions — in one request, send texts (a list of 1–10 strings) instead of text. The same top_k and segments options apply to every item, and the combined length of all items may be up to 20,000 characters (the same cap as a single text, measured after HTML stripping). Exactly one of text and texts must be provided.

curl -X POST https://api.sapling.ai/api/v1/langdetect \
     -H "Content-Type: application/json" \
     -d '{"key":"<api-key>", "texts": ["This is an English sentence.", "Esta es una oración en español."]}'

The batch response is {"results": [...]} with one entry per input, in input order; each entry has the single-response shape above (without segments by default):

{
  "results": [
    {
      "lang": "en",
      "name": "English",
      "conf": 0.98,
      "reliable": true,
      "script": "Latn",
      "candidates": [
        {"lang": "en", "name": "English", "conf": 0.98},
        {"lang": "sco", "name": "Scots", "conf": 0.01},
        {"lang": "nl", "name": "Dutch", "conf": 0.00}
      ]
    },
    {
      "lang": "es",
      "name": "Spanish",
      "conf": 0.99,
      "reliable": true,
      "script": "Latn",
      "candidates": [
        {"lang": "es", "name": "Spanish", "conf": 0.99},
        {"lang": "gl", "name": "Galician", "conf": 0.00},
        {"lang": "pt", "name": "Portuguese", "conf": 0.00}
      ]
    }
  ]
}

With segments: true, each entry's segment offsets index that entry's own tag-stripped text (the same convention as a single request; see segments under Response Parameters). If any item fails to detect, the whole request returns a 400; a retry re-runs the batch (detection is fast, deterministic compute).

Request Parameters​

POST to https://api.sapling.ai/api/v1/langdetect

key: String
32-character API key. Can also be supplied via the Authorization header as a bearer token; if both are provided, the key parameter takes precedence.

text: String
Text to identify the language for. Up to 20,000 characters (HTML tags are stripped before detection). Provide exactly one of text and texts.

texts: List[String]
Batch form (see Batch Requests): 1–10 texts to detect in one request, each treated exactly like text above, with a combined length of up to 20,000 characters. An item that is empty after HTML stripping returns a 400 naming its index. The response becomes {"results": [...]}, one entry per item in input order.

top_k: Integer
Number of language candidates to return, from 1 to 10. Defaults to 3. Applies to the whole text and to each segment.

segments: Boolean
Whether to also detect the language of each segment of the text. Defaults to false. The text is split on line breaks and sentence boundaries; very short fragments are merged with a neighboring sentence on the same line so that tiny snippets don't produce noisy guesses. Use this to find the language of each part of a mixed-language document, or to check whether a document is monolingual.

Response Parameters​

lang: String
The detected language code for the whole text. Mostly two-letter ISO 639-1 codes (en, es, zh, ...); languages without a two-letter code use their ISO 639-2/3 code (ceb, war, ...).

name: String
The English name of the detected language ("English", "Spanish", ...).

conf: Float
Confidence score for the detected language, between 0 and 1. For a mixed-language text the whole-text confidence is typically split across the languages present — look at segments for the per-part picture.

reliable: Boolean
Whether the detection is confident enough to act on. Use this instead of picking your own conf threshold. It is true only when the confidence is high and the text has enough letters, because the detector can be confidently wrong on very short input: "OK" or "Hola" is never reliable, however high its conf. Currently that means a conf above 0.9 and at least 10 letters, with each Chinese, Japanese or Korean character counting as three. A mixed-language text is often unreliable as a whole while each of its segments is reliable.

script: String or null
The dominant writing system of the text, as an ISO 15924 code: the script with the most letters wins. Examples are Latn (Latin), Cyrl (Cyrillic), Grek (Greek), Arab (Arabic), Hebr (Hebrew), Deva (Devanagari), Thai (Thai) and Hang (Korean Hangul). Chinese characters alone give Hani; once the text contains any Japanese kana, its Chinese characters and kana count together as Jpan. Fullwidth and halfwidth forms count as their base script. Letters from a script outside this list give Zzzz, and a text with no letters at all (digits, punctuation or emoji only) gives null. script is computed from the characters themselves, independently of lang, so it can tell Serbian in Cyrillic from Serbian in Latin.

candidates: List
The top top_k languages for the whole text, most likely first. Each item has lang, name and conf. The first candidate is the same as the top-level lang/conf.

segments: List
Only present when segments is true. One item per detected segment, in document order, each with:

  • start, end: character offsets of the segment into the (tag-stripped) input text, such that text[start:end] is the segment.
  • text: the segment text.
  • lang, name, conf, reliable, script, candidates: the detection result for that segment, in the same shape as the top level.