Romanization API

The Romanization API resolves romanized Nepali text or tokens to dictionary-backed Devanagari headwords. It uses the roman aliases materialized in dictionary.db, so results follow the same curated dictionary data used by word lookup.

Endpoints

Method	Endpoint	Description
POST	/api/v1/romanization/resolve	Resolve romanized text or tokens

---

Resolve Romanization

Resolve romanized input token by token. The response includes converted text plus metadata for each roman token.

Request

POST /api/v1/romanization/resolve
Content-Type: application/json

Field	Type	Required	Description
text	string	Yes, unless tokens is provided	Romanized text. Punctuation and whitespace are preserved.
tokens	array[string]	Yes, unless text is provided	Romanized tokens to resolve directly.
max_candidates	integer	No	Maximum candidates per token. Default 5, minimum 1, maximum 10.

Provide either text or tokens.

Example Request

cURLPythonJavaScript

curl -X POST "https://sabdasakha.com/api/v1/romanization/resolve" \
  -H "Content-Type: application/json" \
  -d '{"text": "ma pani khanchu"}'

import requests

response = requests.post(
    "https://sabdasakha.com/api/v1/romanization/resolve",
    json={"text": "ma pani khanchu"},
)
print(response.json()["converted_text"])

const response = await fetch(
  "https://sabdasakha.com/api/v1/romanization/resolve",
  {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({text: "ma pani khanchu"})
  }
);
const result = await response.json();
console.log(result.converted_text);

Success Response (200)

{
  "text": "ma pani khanchu",
  "converted_text": "म पानी khanchu",
  "tokens": [
    {
      "token": "ma",
      "converted": "म",
      "status": "resolved",
      "start": 0,
      "end": 2,
      "candidates": [
        {
          "word": "म",
          "alias": "ma",
          "weight": 100,
          "definition_rank": 10,
          "dictionaries": ["kosha-brihat"],
          "kinds": ["iast"]
        }
      ]
    },
    {
      "token": "pani",
      "converted": "पानी",
      "status": "ambiguous",
      "start": 3,
      "end": 7,
      "candidates": [
        {
          "word": "पानी",
          "alias": "pani",
          "weight": 100,
          "definition_rank": 100,
          "dictionaries": ["kosha-brihat", "kosha-pragya"],
          "kinds": ["iast"]
        },
        {
          "word": "पनि",
          "alias": "pani",
          "weight": 100,
          "definition_rank": 50,
          "dictionaries": ["kosha-brihat"],
          "kinds": ["iast"]
        }
      ]
    },
    {
      "token": "khanchu",
      "converted": "khanchu",
      "status": "unresolved",
      "start": 8,
      "end": 15,
      "candidates": []
    }
  ]
}

Response Fields

Field	Type	Description
text	string|null	Original text when the request used text; otherwise null.
converted_text	string	Input with resolved roman tokens converted. Unresolved tokens are preserved.
tokens	array	Per-token resolution metadata.
tokens[].token	string	Original roman token.
tokens[].converted	string	Selected Devanagari candidate, or the original token when unresolved.
tokens[].status	string	resolved, ambiguous, or unresolved.
tokens[].start	integer|null	Start offset when the request used text.
tokens[].end	integer|null	End offset when the request used text.
tokens[].candidates	array	Ranked dictionary-backed candidates.

Error Response (400)

{
  "detail": "Provide either 'text' or 'tokens'"
}

Notes

• Ambiguous tokens return a selected converted value plus the ranked candidate list, so clients can offer a chooser.
• Unresolved tokens are preserved in converted_text.
• Candidate availability depends on the materialized roman alias tables in the deployed dictionary.db.