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
5 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.

2 Likes

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

2 Likes

Iā€™m working with the Bilara data and I need to get an individual sutta from what I believe is called a ā€œbakedā€ sutta.

For example, I need to get an2.37.

Is it true that the only way I can get this from Bilara (API or otherwise) is if I somehow already know that it is found under an2.32-41?

Here is the background, if itā€™s helpful to understand what I need. Iā€™m creating an Anthology Builder using the Bilara data. The user will give a set of instructions consisting of a list of suttas to include. I can now accommodate selecting a range of segments in a regular sutta like this:

DN 21:2.1.1-2.2.23

I separate what comes before the : and use that as the uid in the API fetch. Then I build the segment numbers by turning that into a starting (dn21:2.1.1) and ending (dn21:2.2.23) segment.

Thatā€™s actually super simple to do and works really well. Yay! Thanks!

Until I try to get something from one of those baked suttas. Then it gets more complicated because I can only use the an2.32-41 to fetch the data and then I have to construct the starting and ending segments from the sutta I actually need, namely an2.37:1.1 and an2.37:10.4

Obviously I can wrangle things to work. But if there was a way for the API to offer up only the debaked sutta, that would be ideal.

2 Likes

Yes, there is no suitable API to do this now. On the front end, I also use the Bilarasutta API to obtain the data and then use js to intercept the relevant sutta.

Let me try to see if I can build a new API to meet this requirement.

3 Likes

Oh, I certianly wouldnā€™t want you to write an api just for me :flushed:

But if I was to really to have my dreams come trueā€¦

I think it would be best if the existing api could be modified so that all the magic happened there. Meaning that anything that worked as an id in a url would also work in the api.

For example, this works:
https://suttacentral.net/an2.36/en/sujato

but this doesnā€™t:
https://suttacentral.net/api/bilarasuttas/an2.36/sujato

If you create a new api, then there would have to be some foreknowledge of which API needed to be used, because one canā€™t tell by looking at the citation alone which api would be needed.

1 Like

Ven. @Snowbird, I created a new API, you can try it:

e.g.

https://suttacentral.net/api/extractsutta/an2.36
or
https://suttacentral.net/api/extractsutta/an2.36/sujato

4 Likes

Oh wow, that was fast! Sadhu sadhu!

Is there a way to use that to get Dhammapada verses? I tried this:

https://suttacentral.net/api/extractsutta/dhp134/sujato

But it didnā€™t work.

3 Likes

Iā€™ve added support for dhp sutta.

But some item about the Vinaya are still being processed.

2 Likes

WOW! That opens up so many interesting possibilities.

I wonder if it would be possible to merge this api with the regular bilara api. That way, especially for parts of the AN, the person using the api wouldnā€™t need to know if a single sutta was part of a larger page. So maybe if the code of the first api failed to find the text, then it could check whatever the logic for the new api is and respond with that.

Just some ideas. Of course we wouldnā€™t want to impact the speed of the existing api since that is used for every bilara website page.

2 Likes

Yes, it can be merged, but it will affect some frontend code, so some modifications to the frontend code are required to merge the two APIs.

3 Likes