API documentation question

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

2 Likes

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.

3 Likes

That’s really nice of you to help, Thx :pray:
I will reply you after checking :smile:

1 Like

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

1 Like

This is the source file of the publication information

Get relevant publication information based on **text_ui**d and **translation_lang_iso**


Yeah :slight_smile:


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 :pray:

1 Like

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 :pray:

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

2 Likes

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 :pray:
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

1 Like

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?

1 Like

It’s probably in the name files, most likely in super-name.

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.

1 Like

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.

1 Like

Hi @Snowbird ,can be obtained from this API:
For example:
http://localhost/api/menu/mn-mulapariyayavagga

1 Like

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!

1 Like