Skip to content

API Endpoints

Here are the API endpoints available in the DPD Web App (exporter/webapp). The application is built using FastAPI.

The website is online here https://www.dpdict.net/

All API endpoints can be tested here https://www.dpdict.net/docs

Licensing

DPD dictionary data is released under CC BY-NC-SA 4.0 — attribution required, non-commercial use only, derivatives shared alike.

Every endpoint that returns dictionary data (/search_json, /search_html, /gd) sends the licence as an RFC 8288 link header:

Link: <https://creativecommons.org/licenses/by-nc-sa/4.0/>; rel="license"; title="CC BY-NC-SA 4.0"

/search_json additionally ends its response body with a license object.

The rendered entries themselves end with a small visible notice — the four Creative Commons marks (inlined SVG, so they survive offline in GoldenDict) followed by Digital Pāḷi Dictionary CC BY-NC-SA 4.0, linking to the deed. It is appended to the results HTML rather than to a page footer, so it travels with the data into GoldenDict, the JSON dpd_html field and any third-party embed of the fragment. A "no results" page carries no notice.

Busy answers

/search_json, /search_html and /gd take turns: two lookups run at a time and up to 20 more wait for up to 20 seconds. Anyone beyond that, or still waiting after 20 seconds, gets HTTP 503 with a Retry-After: 10 header, the same cross-origin and licence Link headers as a normal answer and the text "The server is busy. Try again in a moment." /search_json keeps its normal shape (summary_html empty, the text in dpd_html, plus license), so the web page shows the message. /bd_search and /tt_search have their own turn-taking, described under each. Only GET requests take turns: a browser's cross-origin preflight (OPTIONS) is answered at once. Other routes such as /status and /audio/{headword} are never held up.

Tipiṭaka translations (/tt_search), bold definitions (/bd_search) and audio (/audio/{headword}) are licensed separately and carry none of the above.

Web Pages

Home Page

  • URL: /
  • Method: GET
  • Description: Renders the main home page of the dictionary.
  • Parameters: None
  • Response: HTML (home.html)

Bold Definitions Page

  • URL: /bd
  • Method: GET
  • Description: Renders the landing page for Bold Definitions search.
  • Parameters: None
  • Response: HTML (home.html)
  • URL: /{headword_id}
  • Method: GET
  • Description: The permanent link to one entry, eg /24043, used in citations. Redirects to the entry's search page. The path only matches digits, so no named route can fall into it.
  • Parameters:
    • headword_id (path parameter): The headword id. Ids are never reused.
  • Response: 308 Permanent Redirect to /?q={headword_id}

Search Endpoints

  • URL: /search_html
  • Method: GET
  • Description: Performs a dictionary search and returns the results rendered within the home page template. Used for direct page loads with search results.
  • Parameters:
    • q (str): The search query (Pali word or English term).
  • Response: HTML (home.html populated with results)
  • URL: /search_json
  • Method: GET
  • Description: Main search route for the website's dynamic search functionality. Returns the rendered HTML fragments for the results and summary.
  • Parameters:
    • q (str): The search query.
  • Response: JSON 
    {
    "summary_html": "...",
    "dpd_html": "...",
    "license": {
        "name": "CC BY-NC-SA 4.0",
        "url": "https://creativecommons.org/licenses/by-nc-sa/4.0/",
        "attribution": "Digital Pāḷi Dictionary by Bodhirasa Bhikkhu CC BY-NC-SA 4.0",
        "note": "Non-commercial use only. Derivatives must be shared alike."
    }
}
  • URL: /gd
  • Method: GET
  • Description: Returns a simplified HTML version of the search results, optimized for external dictionary applications like GoldenDict and MDict.
  • Parameters:
    • search (str): The search query.
  • Response: HTML (home_simple.html)

Check out this guide for setting up the API in GoldenDict or DictTango on Android

  • URL: /bd_search
  • Method: GET
  • Description: Search route specifically for "Bold Definitions" (commentarial definitions).
  • Parameters:
    • q1 (str): Primary search query.
    • q2 (str): Secondary search query (context or additional filter).
    • option (str): Search option/mode.
  • Limits: At most 100 results are shown. When more exist the page says "100+ results found". The regex search has the same time budget, pattern rules and turn-taking as /tt_search. When a search is stopped the page shows the same message in place of the result count.
  • Response: HTML (bold_definitions.html with results)
  • URL: /tt_search
  • Method: GET
  • Description: Searches through Tipiṭaka translations.
  • Parameters:
    • q (str): Search query.
    • book (str): Specific book to search in, or "all".
    • lang (str): Language/Column to search ("Pāḷi" or others).
  • Limits:
    • q is stripped. An empty q returns {"total": 0, "results": []} without searching.
    • Repeated books in book are searched once.
    • At most 100 results are returned. The server stops reading at 101 matches, so total is the number found up to 101: 101 means "more than 100", not an exact count.
    • Each request has a budget of 4 seconds of the search's own CPU time for the regex search (waiting for a turn does not use it), with a 20 second wall-clock backstop.
    • q is a regular expression, case-sensitive. A pattern over 2000 characters, with very large repeat counts such as (?:a{3000}){3000}, or using recursion ((?R), (?1)) is refused as too complex. An invalid pattern is refused as not valid. Regex searches take turns: one runs at a time, up to three more wait their turn for up to 10 seconds, and anyone beyond that is told the server is busy.
  • Response: JSON 
    {
    "total": 100,
    "results": [
        {
            "id": 1,
            "pali": "...",
            "eng": "...",
            "book": "...",
            "table": "..."
        }
    ]
}
    If the search is stopped, results is empty and an error text is added. The text is one of: "The search took too long. Use a more specific search.", "That search pattern is not valid.", "That search pattern is too complex. Use a simpler pattern.", "The server is busy. Try again in a moment." 
    {
    "total": 0,
    "results": [],
    "error": "The search took too long. Use a more specific search."
}

Resources

Audio

  • URL: /audio/{headword}
  • Method: GET
  • Description: Serves the audio file for a specific headword with byte-range support.
  • Parameters:
    • headword (path parameter): The headword to retrieve audio for.
    • gender (query parameter, optional): Preferred voice gender ("male" or "female"). Defaults to "male".
  • Response: Audio file (audio/mpeg). Returns 200 OK for full file, 206 Partial Content for range requests, or 404 Not Found if the headword does not exist.

Examples: - GET /audio/buddha?gender=male - GET /audio/buddha?gender=female - GET /audio/dhamma?gender=male - GET /audio/dhamma?gender=female - GET /audio/saṅgha?gender=male - GET /audio/saṅgha?gender=female