---
title: "Analyze directionality"
method: POST
path: "/v1/analyze"
tags: ["Directionality"]
---

# Analyze directionality

`POST /v1/analyze`

## Request

- Base URL: `https://hc.itsbaba.com`
- URL: `https://hc.itsbaba.com/v1/analyze`
- Auth: HTTP bearer

Resolve the RTL/LTR structure of one string (`text`) or a whole record at once (`fields`, a map of name → string). Returns the base direction, whether the text mixes directions, the dominant language and script, and two run lists: `runs` exactly as the Unicode Bidirectional Algorithm resolves them, and `display_runs` that keep every left-to-right unit (a price, a range, a date, a model number) whole.

**Quota.** Deterministic, no model. Does not consume the character quota; counts toward the rate limit only.

**Limits.** Send exactly one of `text` or `fields`. Up to 100 fields and 20,000 characters in total. Idempotent: the same input always gives the same output.

## Request body

- object: Provide exactly one of `text` (a single string) or `fields` (a map of name → string). Max 20,000 chars per string; up to 100 fields.
  - `text` string: A single string, up to 20,000 characters. Send this or `fields`.
  - `fields` object: A map of field name → string, up to 100 fields and 20,000 characters in total. Send this or `text`.
  - `base` 'auto' | 'ltr' | 'rtl': Paragraph direction to resolve against. `auto` (default) uses the first strong letter.

## Response `200`

Directionality analysis

- AnalyzeResponse
  - `analysis` object: Present when the request sent `text`.
    - `dir` 'ltr' | 'rtl', required: Paragraph base direction. With `base: "auto"` this follows the Unicode first-strong rule, matching CSS `dir="auto"`.
    - `mixed` boolean, required: True when the text contains both strong right-to-left and strong left-to-right letters. Digits and invisible marks do not count.
    - `lang` string, required: Dominant BCP 47 language, from the dominant script.
    - `script` string, required: Dominant ISO 15924 script.
    - `runs` DirectionRun[], required: Runs exactly as the Unicode Bidirectional Algorithm resolves them.
      - `text` string, required: The run text. Equals `input.slice(start, end)`.
      - `dir` 'ltr' | 'rtl', required: Resolved direction of the run.
      - `script` string, required: ISO 15924 script of the run: `Hebr`, `Latn`, `Cyrl`, `Arab`, or `Zyyy` for digits and punctuation only.
      - `lang` string, required: Best-effort BCP 47 language of the run, from its script. `und` when undetermined (numbers, symbols).
      - `start` integer, required: UTF-16 offset of the first character, inclusive.
      - `end` integer, required: UTF-16 offset after the last character, exclusive.
    - `display_runs` DirectionRun[]: Runs for display: every left-to-right unit (a Latin term, a number with its unit, a range, a date, a percentage, a comparison such as <5) is one run, so it never splits or mirrors. Render these, or use /v1/wrap.
      - `text` string, required: The run text. Equals `input.slice(start, end)`.
      - `dir` 'ltr' | 'rtl', required: Resolved direction of the run.
      - `script` string, required: ISO 15924 script of the run: `Hebr`, `Latn`, `Cyrl`, `Arab`, or `Zyyy` for digits and punctuation only.
      - `lang` string, required: Best-effort BCP 47 language of the run, from its script. `und` when undetermined (numbers, symbols).
      - `start` integer, required: UTF-16 offset of the first character, inclusive.
      - `end` integer, required: UTF-16 offset after the last character, exclusive.
  - `fields` object: Present when the request sent `fields`: one analysis per field name.

## Other responses

- `400`: Invalid request: the body failed validation or a value is out of range.
- `401`: Missing, malformed, invalid or revoked API key.
- `402`: A new self-serve account must save a card in the console before it can use the API. Adding a card is free.
- `403`: The connection used TLS older than 1.2.
- `429`: Too many requests this minute. Retry after a short wait.
- `500`: Unexpected server error. Safe to retry.

---

[API](https://skmtc.dev/itsbaba/apis/hebrewcore-api.md) · [All operations](https://skmtc.dev/itsbaba/apis/hebrewcore-api/llms.txt) · [OpenAPI document](https://skmtc.dev/itsbaba/apis/hebrewcore-api/revisions/f54229695236?raw)