Api

api

Kotobase's Public API

Kotobase is a thin, stateless wrapper over the Unit Of Work which queries the databases

Each call opens one read-only session, runs the queries it needs through the repositories and returns plain Data Transfer Objects

The queries in a lookup run sequentially on a single session, which is both simple and correct for read-only SQLite

Kotobase

Stateless entry point for querying the kotobase database

__call__(query, *, wildcard=False, include_names=False, sentence_limit=50, entry_limit=None, with_labels=False)

Run a comprehensive lookup, an alias for lookup

Parameters:

Name	Type	Description	Default
query	str	The query, written in kana or kanji	required
wildcard	bool	When True, match forms as a LIKE pattern	False
include_names	bool	When True, also search JMnedict proper names	False
sentence_limit	int	Maximum number of example sentences to return	50
entry_limit	int | None	Maximum number of dictionary entries to return, or None for no limit	None
with_labels	bool	When True, resolve tag codes to descriptions	False

Returns:

Type	Description
LookupResult	A LookupResult for the query

audio(key, *, kind=None)

Return pronunciation audio metadata for a lookup key

Parameters:

Name	Type	Description	Default
key	str	The lookup key, such as a kanji or word	required
kind	str | None	Restrict to a clip kind when given	None

Returns:

Type	Description
list[AudioDTO]	The matching audio clips as metadata, without the raw bytes

Raises:

Type	Description
AudioDatabaseNotFoundError	If the optional audio pack is not installed

audio_bytes(key, *, reading=None, kind=None)

Return the file name and raw bytes of each matching audio clip

Parameters:

Name	Type	Description	Default
key	str	The lookup key, such as a kanji or word	required
reading	str | None	Select a specific clip by its reading, or None to return every matching clip	None
kind	str | None	Restrict to a clip kind when given	None

Returns:

Type	Description
list[tuple[str, bytes]]	A file name and bytes pair for every matching clip, empty when nothing matches

Raises:

Type	Description
AudioDatabaseNotFoundError	If the optional audio pack is not installed

by_radicals(radicals)

Return the kanji that contains every one of the given radicals

Parameters:

Name	Type	Description	Default
radicals	list[str]	The radical components to require	required

Returns:

Type	Description
list[KanjiDTO]	The full details of each matching kanji

db_info()

Return the build metadata recorded in the database

Returns:

Type	Description
dict[str, str]	A mapping of metadata key to value, such as the build date, schema version and database size

Raises:

Type	Description
DatabaseNotFoundError	If the database does not exist

expand_tags(codes)

Expand tag codes to their human readable descriptions

Parameters:

Name	Type	Description	Default
codes	list[str]	The tag codes to expand	required

Returns:

Type	Description
dict[str, str]	A mapping of code to description for those that are known

furigana(word, reading=None)

Return furigana segmentation for a written form

Parameters:

Name	Type	Description	Default
word	str	The written spelling to look up	required
reading	str | None	A specific reading to narrow the match	None

Returns:

Type	Description
list[FuriganaDTO]	The matching furigana segmentations

jlpt_level(word)

Return the JLPT vocabulary level of a word

Parameters:

Name	Type	Description	Default
word	str	The word to look up	required

Returns:

Type	Description
int | None	The JLPT level from 1 to 5, or None when the word is not listed

jlpt_list(kind, level)

Return a full Tanos JLPT study list

Parameters:

Name	Type	Description	Default
kind	str	One of vocab, kanji or grammar	required
level	int	The JLPT level from 1 to 5	required

Returns:

Type	Description
list[JLPTVocabDTO] | list[JLPTKanjiDTO] | list[JLPTGrammarDTO]	Every item of the requested kind at the level

Raises:

Type	Description
ValueError	If kind is not a known JLPT list kind

kanji(literal)

Return the full profile of a single kanji

Parameters:

Name	Type	Description	Default
literal	str	The kanji literal	required

Returns:

Type	Description
KanjiDTO | None	The kanji details, or None when it is not in the database

kanji_by_skip(code, *, limit=100)

Find kanji with a given SKIP query code

Parameters:

Name	Type	Description	Default
code	str	The SKIP code such as 1-4-3	required
limit	int	Maximum number of kanji to return	100

Returns:

Type	Description
list[KanjiDTO]	The matching kanji as data transfer objects

lookup(query, *, wildcard=False, include_names=False, sentence_limit=50, entry_limit=None, with_labels=False)

Run a comprehensive lookup across every data source

Parameters:

Name	Type	Description	Default
query	str	The query, written in kana or kanji, where * and % act as wildcards when wildcard is True	required
wildcard	bool	When True, match forms as a LIKE pattern	False
include_names	bool	When True, also search JMnedict proper names	False
sentence_limit	int	Maximum number of example sentences to return	50
entry_limit	int | None	Maximum number of dictionary entries to return, or None for no limit	None
with_labels	bool	When True, resolve every tag code in the result to its human-readable description and store them on the result	False

Returns:

Type	Description
LookupResult	A LookupResult aggregating entries, names, kanji, furigana, JLPT data and example sentences

names(form=None, *, name_type=None, wildcard=False, limit=50)

Look up or browse JMnedict proper names

Parameters:

Name	Type	Description	Default
form	str | None	A written or reading form to search for	None
name_type	str | None	A name type to browse, such as place	None
wildcard	bool	When True, match the form as a LIKE pattern	False
limit	int	Maximum number of names to return	50

Returns:

Type	Description
list[JMNeDictEntryDTO]	The matching names, empty when neither a form nor a type is given

radicals()

Return every search radical with its stroke count

Returns:

Type	Description
list[RadicalDTO]	The radicals ordered by stroke count

save_audio(key, dest, *, reading=None, kind=None)

Save the matching pronunciation audio clips into a directory

Parameters:

Name	Type	Description	Default
key	str	The lookup key, such as a kanji or word	required
dest	str | Path	The directory to write the clips into, created when it does not exist	required
reading	str | None	Save only the clip with this reading when given	None
kind	str | None	Restrict to a clip kind when given	None

Returns:

Type	Description
list[Path]	The paths of the written audio files

Raises:

Type	Description
AudioDatabaseNotFoundError	If the optional audio pack is not installed

search_kanji(*, stroke_count=None, grade=None, freq_max=None, jlpt=None, limit=100)

Search kanji by its scalar attributes

Parameters:

Name	Type	Description	Default
stroke_count	int | None	Required stroke count	None
grade	int | None	Required school grade	None
freq_max	int | None	Maximum newspaper frequency rank	None
jlpt	int | None	Required Tanos JLPT level	None
limit	int	Maximum number of kanji to return	100

Returns:

Type	Description
list[KanjiDTO]	The matching kanji ordered by frequency then character

search_meaning(query, *, limit=50)

Return entries whose English meaning matches the query

Parameters:

Name	Type	Description	Default
query	str	The full text search expression to run against glosses	required
limit	int	Maximum number of entries to return	50

Returns:

Type	Description
list[JMDictEntryDTO]	The matching dictionary entries

sentences(text_value, *, limit=20)

Return Tatoeba Japanese example sentences containing the given text

Parameters:

Name	Type	Description	Default
text_value	str	The text to search for	required
limit	int	Maximum number of sentences to return	20

Returns:

Type	Description
list[SentenceDTO]	The matching example sentences

stroke_svg(literal, *, raw=False)

Return a kanji's stroke order as SVG

By default this returns a self-contained, browser renderable SVG document. Pass raw to get the original KanjiVG <kanji> fragment instead, which has no <svg> root or styling

Parameters:

Name	Type	Description	Default
literal	str	The kanji character	required
raw	bool	When True, return the raw KanjiVG fragment unwrapped	False

Returns:

Type	Description
str | None	The stroke order SVG, or None when not available