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

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}'

JavaScript

import axios from 'axios';

async function run(text) {
    try {
        const response = await axios.post(
            'https://api.sapling.ai/api/v1/langdetect',
            {
                key: '<api-key>',
                text,
                segments: true,
            },
        );
        const {status, data} = response;
        console.log({status});
        console.log(JSON.stringify(data, null, 4));
    } catch (err) {
        const { msg } = err.response.data;
        console.log({err: msg});
    }
}

run('This is an English sentence. Esta es una oración en español.');

Python

import requests
from pprint import pprint

response = requests.post(
    "https://api.sapling.ai/api/v1/langdetect",
    json={
        "key": "<api-key>",
        "text": "This is an English sentence. Esta es una oración en español.",
        "segments": True,
    }
)

if 200 <= response.status_code < 300:
    pprint(response.json())
else:
    print('Error: ', response.status_code, response.text)

Python (Sapling client)

from sapling import SaplingClient

api_key = '<api-key>'
client = SaplingClient(api_key=api_key)
result = client.langdetect(
    'This is an English sentence. Esta es una oración en español.',
    segments=True,
)
print(result['lang'], result['name'], result['conf'])
for segment in result['segments']:
    print(segment['lang'], segment['text'])

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.

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).

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.