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. 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,
    "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,
            "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,
            "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 and candidates.

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,
      "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,
      "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.

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, candidates: the detection result for that segment, in the same shape as the top level.