[API Docs] Get Bilara Sutta Texts

Say you want to get a sutta translation or root text that has been created in the Bilara segmentation system. As long as you have a correct citation (aka uid) and you know the name of the translator or name of the root text then you can easily fetch the text you want.

[ All API documentation | General discussion on SC APIs ]

Requesting a translation text

Pattern:

https://suttacentral.net/api/bilarasuttas/<uid>/<translator-id>

Example URL: https://suttacentral.net/api/bilarasuttas/sn7.5/sujato

Returns:

html_text:{

An object of the html wrapper for each segment. Keys are the segments. E.g.:

sn7.5:2.1	"<blockquote class='gatha'><p><span class='verse-line'>{}</span>"

The translation and/or root text should be inserted in place of the {} pair.
}

reference_text:{

An object of the manuscript references for each segment, when they exist. Keys are the segments ids. E.g.:

sn7.5:1.1:	"cck15.220, ms12S1_1159, …191, pts-vp-pli1ed1.165"

}

root_text:{

An object of the root text (e.g. Pāli) for each segment. Keys are the segments ids. E.g.:

sn7.5:2.4:"manasā ca na hiṁsati; "

Segments should always end with a blank space.
}

translation_text:{

An object of the translation text (e.g. English) for each segment. Keys are the segments ids. E.g.:

sn7.5:2.1: "“If you were really like your name, "

Segments should always end with a blank space.
}

keys_order:[

An array of all the segment ids in the correct sort order. E.g.:

["sn7.5:0.1", "sn7.5:0.2", "sn7.5:0.3", ...]

]

Requesting a root text

If you would like to request only the root text, you need to know the id for that text.

https://suttacentral.net/api/bilarasuttas/<uid>/<text-id>

For example the Pāli text id is ms.

Example URL: https://suttacentral.net/api/bilarasuttas/sn7.5/ms

This returns the same information as the previous example but without the translation_text.

Errors

If there is no matching text, the following will be returned:

msg: "Not Found"

If an invalid translator or root text id is given, only html_text, reference_text, root_text and keys_order is returned.

Parameters

At present, the lang=en, etc., parameter is only used as a reserved parameter and will not affect the query result.

Code Examples

Once you have fetched the data, the following code could be used to build an html string for presenting the translation with root text. It is good to handle the situation where a segment could be undefined in either the root or translation text. The code below shows two different ways of doing this. For the translation_text[segment] it is done with an if statement. For the root_text it is done with a conditional (ternary) operator.

let html="";
keys_order.forEach(segment => {
    if (translation_text[segment] === undefined) {
      translation_text[segment] = "";
    }

    let [openHtml, closeHtml] = html_text[segment].split(/{}/);

    html += `${openHtml}<span class="segment" id ="${segment}"><span class="pli-lang" lang="pi">${
      root_text[segment] ? root_text[segment] : ""
    }</span><span class="eng-lang" lang="en">${translation_text[segment]}</span></span>${closeHtml}\n\n`;
  });

Example projects

Note: This is post is a wiki. Please feel free to click the edit button below to make changes. Feel free to reply to the post if you have questions
2 Likes

For my own understanding and reference, I thought to create some documentation for the various SC APIs. This one is the most straightforward, so I thought to start with it. Bhante @Sujato and @HongDa, when you have a moment could you offer any feedback? Or if a document like this already exists, could you please let me know where it is and we could delete this one.

@moderators, would it be possible to create a API Documentation tag? That way it would be easy to link to all of them at once.

For non-tech people who have stumbled onto this post, an API (application program interface) is kind of like a website, but instead of returning a web page (like https://suttacentral.net/sn7.5/en/sujato) it returns structured information that a computer can easily read (like https://suttacentral.net/api/bilarasuttas/sn7.5/sujato). This allows people to write software/apps that can use SuttaCentral data in new and interesting ways.

1 Like

If anything is unclear about the API, please let me know. :pray:

2 Likes