Annotate a passage

POST/v1/annotate

A row for each word of a passage: where it is, its language, its base form, the reading chosen with the other readings the written form has, the inflected form it is written in, the headword's pitch accent, how common the word is, its word class and the entry's first gloss. A word is the longest run the dictionary holds as one written form. Every character of the passage draws from the balance, and the passage is not stored.

Parameters

passagestringrequiredbody
The text to annotate, in Japanese, English or both. The script of each word decides its language. At most 5000 characters, counted as Unicode code points

Response200PassageAnnotation

charactersintegerrequired
The characters the passage has, each drawn from the balance
rowsPassageRow[]required
A row for each word, in the order the passage writes them. Punctuation and symbols have no row
PassageRow
surfacestringrequired
The word as the passage writes it: the longest run the dictionary holds as one written form, so 見に行きました is one row
startintegerrequired
Where the surface starts in the passage, in Unicode code points from 0
endintegerrequired
Where the surface ends, exclusive
lang"eng" | "jpn"required
headwordstringrequirednullable
The base form: the headword of the word's entry, which the entry route answers in full. Null for a word with no entry, a name for example, which has a reading and nothing else below
readingstringrequirednullable
jpn only. The reading chosen for the surface, in kana. A written form can have several readings, and `other_readings` lists the rest
other_readingsstring[]required
jpn only. Every other reading the written form has
formPassageFormrequirednullable
The inflected form the word is written in; null for a word in its base form
PassageForm
namestringrequired
The form's name in the word's language: 過去形, past tense
translationsobjectrequired
The form's name by language: {"eng": "past"}
translations.{key}string
polarity"positive" | "negative"requirednullable
jpn only
tone"plain" | "polite"requirednullable
jpn only
accentintegerrequirednullable
jpn only. The headword's pitch accent, the mora after which the pitch falls and 0 for none; an inflected form carries its headword's. Null where the entry has none
frequency_band"very_common" | "common" | "uncommon" | "rare" | "very_rare"requirednullable
How common the entry is in its language, in five bands. Null for a word with no entry and for an entry the dictionary has not ranked
posstringrequirednullable
The word class, named in the word's language
glossstringrequirednullable
The entry's first gloss under the reading chosen, in the other language: not the sense the passage uses

Errors

StatusCodeWhen
401
unauthorizedapi_key_invalidapi_key_revokedapi_key_suspended
No key, or a key that is invalid, revoked or suspended.
402
balance_empty
The account's balance is empty. Top up, or wait for the free allowance to return.
403
entry_limit_reached
The answer would take the account past its limit on different entries. The entries it has read keep answering.
429
rate_limited
The burst is used. Read retry-after.
422
requiredtoo_long
The passage is missing or empty, or longer than one call takes.