@HongDa, Bhante Sujato mentioned that you might be able to help with documentation for the SC API. I’d love to help with writing some if that would be beneficial.
By looking at the network tab in the dev tools I can see a few different things happening
Basic sutta content
https://suttacentral.net/api/bilarasuttas/sn7.5/sujato?lang=en
This returns four types of data:
- reference_text
- root_text
- translation_text
- html_text
- keys_order
It seems like the ?lang=en
bit isn’t doing anything.
SutaPlex
https://suttacentral.net/api/suttas/sn7.5/sujato?lang=en&siteLanguage=en
In addition to everything on a SuttaPlex card, this also contains the citations/names for the previous and next suttas.
And again, ?lang=en&siteLanguage=en
seems to have no effect.
https://suttacentral.net/api/suttas/sn7.5
(this has sujato
removed)
Looks like the same SuttaPlex info but without the previous and next information?
Menu
https://suttacentral.net/api/menu/linked?language=en
https://suttacentral.net/api/menu/sutta?language=en
etc.
This appears to be the information needed to bulid each level of menu.
Publication info
https://suttacentral.net/api/publication_info/sn7.5/en
This one is curious because it gives the publication info for Bhante Sujato’s translation, but I don’t see how that is indicated in the url
Misc
https://suttacentral.net/api/suttafullpath/sn7.5
produces this:
"/pitaka/sutta/linked/sn/sn-sagathavaggasamyutta/sn7/sn7-arahantavagga"
https://suttacentral.net/api/pali_reference_edition
This looks like a dictionary for the regrence abbreviations.
https://suttacentral.net/api/expansion
Some other kind of dictionary of abbreviations?
https://suttacentral.net/api/guides
uids for all the guides?
https://suttacentral.net/api/shortcuts
Unclear what this is.
https://suttacentral.net/api/languages?all=true
All the languages on the site?
With ?all=true
54 items are returned. Without, 45.
That’s really nice of you to help, Thx
I will reply you after checking
Let’s take DN1 as an example
https://suttacentral.net/api/bilarasuttas/dn1/sujato?lang=en
It seems like the?lang=en
bit isn’t doing anything.
At present, the lang
parameter is only used as a reserved parameter and will not affect the query result.
Suttaplex pages are mainly provided with data by this API
https://suttacentral.net/api/suttaplex/dn1?language=de
https://suttacentral.net/api/suttas/dn1/sujato?lang=en&siteLanguage=de
If author
and lang
parameter is passed, root_text
and translation
results are empty if there is no relevant result, siteLanguage
will affect candidate_authors
result.
This appears to be the information needed to bulid each level of menu.
This API provides the main structure
https://suttacentral.net/api/menu?language=en
This is the source file of the publication information
Get relevant publication information based on **text_ui**d
and **translation_lang_iso**
Yeah
This API lists all existing guides
https://suttacentral.net/api/shortcuts
This API is mainly used in navigation to list navigation items suitable for linking to suttaplex page
If all=true, all languages including root text language will be returned, otherwise no root text language will be returned.
I don’t know if what I said is clear, please let me know if there is anything unclear
Oh, I never responded! Very sorry. This was all extremely helpful.
Small question about the suttaplex api:
Please forgive such a basic question… I noticed that the data for Bhante Sujato is in a different order from the others. I know that technically objects don’t have an order to the data, but is there a reason it is different in this case?
No worries:)
glad to help you
Yes, it is not sorted when it is taken out from the database, but the translations result is merged from two kinds of data, one is segmented text, the other is legacy text, and in segmented text, most of the English versions are only Bhante Sujato’s translation, so Bhante’s English translation will come first
Question about this API and suttas that are part of a range. As a regular link, the following works:
https://suttacentral.net/an1.1/en/sujato
However this call to the API returns msg "Not Found"
https://suttacentral.net/api/bilarasuttas/an1.1/sujato?lang=en
Is there any way to get individual suatta through the API, or is this something you are handling after the API call on the real site?
Hey @Snowbird sorry for replying so late
an1.1 belongs to an1.1-10, so you need to get data like this:
https://suttacentral.net/api/bilarasuttas/an1.1-10/sujato?lang=en&sitelanguage=en
Thanks! That’s what I thought. I was just hoping that since suttacentral.net/an1.1/en/sujato works as a url, that there was some way it could be done through the API.
The relevant range_id can be obtained by doing this:
https://suttacentral.net/api/suttas/an1.1
Bhante @Sujato, I’m wondering if all of this information should be put into a readme somewhere. I’m happy to give it a try if you like. Just tell me where.
@HongDa, if you have time, I’m wondering if there is a way through the api that I can get the name of the “chapter” that a sutta is in. And by this, I am referring to the 3 chapters of the DN and the 15 chapters of the MN, or the 56 chapters of the SN. Not the other levels of divisions.
For example, a way to know that MN1 was in “The Chapter on the Root of All Things”. It’s not in the sutta json that I can see. And I’m not seeing it returned in the /api/suttaplex/
, /api/suttas/
or /api/bilarasuttas/
The reason being is that I am trying to generate pages for these chapter titles in an ebook I’m generating. Some of the KN books have chapter titles in the sutta files themselves. The SN has the vagga a sutta is in, but I’m after the samyutta (1 through 56)
It’s in the breadcrumbs and other places, but I just can’t figure out where to grab it from. Is it outside of Bilara?
Hmm. That does have them. But I’m not sure how I could use that programmatically. Here is the MN file. It looks like it is missing a bunch of sutta names, though.
Yes, it usually has only up to the level of vagga names (“vagga” as meaning “chapter with 10 or so Suttas”, not the great vaggas of the SN). SC picks the names of the Suttas from the Sutta files themselves.
Hi @Snowbird ,can be obtained from this API:
For example:
http://localhost/api/menu/mn-mulapariyayavagga
Thanks! I didn’t know you could do that.
But what I’m looking for is a way to know that, say, MN2 would be inside mn-mulapariyayavagga
. There may not be a way with the API.
I was eventually able to get what I wanted by manually adding the chapter headings to my array of sutta ids for each book. That is probably a better solution for what I needed anyway.
Thanks!