Data Models

The Shobdo API is designed for simplicity and speed. Rather than exposing complex, deeply-nested linguistic graph databases directly to the client, the API aggregates and flattens data into easy-to-consume models.

There are two primary data structures you will work with: the SearchResult (for lists and autocomplete) and the FullEntry (for retrieving the complete contents of a specific word).

All responses are wrapped in a standard API envelope.

The Standard API Response

Every endpoint returns a consistent JSON envelope to make error handling and pagination predictable.

interface ApiResponse<T> {
  ok: boolean;
  data: T;
  meta?: {
    total?: number;
    limit?: number;
    offset?: number;
    took_ms?: number;
  };
  error?: string;
}

ok: A boolean indicating success or failure. Check this first.
data: The actual payload (e.g., an array of SearchResult objects or a single FullEntry).
meta: Pagination details and performance metrics.
error: A human-readable error message, present only if ok is false.

SearchResult Object

The SearchResult object is returned by the /search, /autocomplete, and /examples endpoints. It is intentionally lightweight, containing just enough information to render a list of results, a preview, and audio controls.

Field	Type	Description
`id`	`string`	The unique identifier for this specific dictionary entry.
`word`	`string`	The headword (e.g., "hello").
`preview`	`string`	A plain-text snippet of the primary definition for UI previews.
`sourceLang`	`string`	The ISO 639-1 language code of the headword (e.g., "en", "bn").
`targetLang`	`string \| null`	For bilingual dictionaries, the translation language code.
`dictionaryId`	`string`	The internal ID of the dictionary this result belongs to.
`dictionaryName`	`string`	The human-readable name of the dictionary.
`partOfSpeech`	`string`	The grammatical category (e.g., "noun", "verb"). Optional.
`phonetic`	`string`	The IPA pronunciation (e.g., `/həˈloʊ/`). Optional.
`hasAudio`	`boolean`	True if a high-quality human audio recording is available for this entry.

FullEntry Object

The FullEntry object is returned by the /entry/{source}/{id} and /entry/{source}/word/{word} endpoints. It contains the complete, unabridged dictionary entry.

Unlike many dictionary APIs that force you to traverse complex arrays of senses, sub-senses, and grammatical notes, the Shobdo API handles the heavy lifting on the backend. The htmlContent field provides pre-rendered, semantically correct HTML that preserves the original dictionary's typography (italics, bolding, lists) perfectly.

Field	Type	Description
`id`	`string`	The unique identifier for this entry.
`word`	`string`	The headword.
`htmlContent`	`string`	The complete, richly-formatted HTML dictionary article. Ready to be injected into the DOM.
`plainText`	`string`	A stripped version of `htmlContent` containing only the raw text definitions.
`sourceLang`	`string`	The source language code.
`targetLang`	`string \| null`	The target language code (if bilingual).
`dictionaryId`	`string`	The ID of the dictionary.
`dictionaryName`	`string`	The human-readable name of the dictionary.
`partOfSpeech`	`string`	The primary part of speech. Optional.
`phonetic`	`string`	The IPA pronunciation. Optional.
`synonyms`	`Array<string>`	A list of related words with similar meanings. Optional.
`antonyms`	`Array<string>`	A list of related words with opposite meanings. Optional.
`examples`	`Array<string>`	A list of usage sentences. Optional.
`hasAudio`	`boolean`	True if audio is available.
`audioUrl`	`string`	A direct, pre-signed URL to the MP3/OGG file on our edge CDN. Optional.

Note on htmlContent

The htmlContent field is sanitized and safe to render using standard framework mechanisms (e.g., dangerouslySetInnerHTML in React, or v-html in Vue). It utilizes standard semantic tags (<b>, <i>, <ul>, <li>, <span>) without relying on proprietary CSS classes, ensuring it inherits your application's typography automatically.

Putting it all together

Here is an example of a complete response when fetching a FullEntry for the word "hello":

{
  "ok": true,
  "data": {
    "id": "12345",
    "word": "hello",
    "htmlContent": "<b>1.</b> an expression of greeting.<br><b>2.</b> used to express surprise.",
    "plainText": "1. an expression of greeting. 2. used to express surprise.",
    "sourceLang": "en",
    "targetLang": null,
    "dictionaryId": "shobdo_mono_en_1",
    "dictionaryName": "English Advanced Dictionary",
    "partOfSpeech": "noun",
    "phonetic": "/həˈləʊ/",
    "synonyms": ["hi", "greetings", "salutations"],
    "antonyms": ["goodbye", "farewell"],
    "examples": ["Hello, how are you?", "She said hello to the crowd."],
    "hasAudio": true,
    "audioUrl": "https://api.shobdo.me/api/v1/audio/shobdo_mono_en_1/12345"
  },
  "meta": {
    "took_ms": 12
  }
}