API documentation question

Snowbird · April 22, 2022, 1:44am

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

Snowbird · April 22, 2022, 11:05am

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?

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.

HongDa · April 25, 2022, 2:13am

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

HongDa · April 25, 2022, 1:07pm

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

HongDa · April 25, 2022, 1:15pm

This is the source file of the publication information

github.com

suttacentral/sc-data/blob/master/sc_bilara_data/_publication.json

{
  "scpub1": {
    "publication_number": "scpub1",
    "root_lang_iso": "pli",
    "root_lang_name": "Pali",
    "translation_lang_iso": "en",
    "translation_lang_name": "English",
    "source_url": "https://github.com/suttacentral/bilara-data/tree/published/translation/en/sujato/sutta/kn/thag",
    "author_uid": "sujato-walton",
    "collaborator": [
      {
        "collaborator_uid": "sujato",
        "author_name": "Bhikkhu Sujato",
        "author_github_handle": "sujato"
      },
      {
        "collaborator_uid": "walton",
        "author_name": "Jessica Walton",
        "author_github_handle": ""
      }

This file has been truncated. show original

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

Snowbird · May 9, 2022, 2:40am

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?

HongDa · May 9, 2022, 9:02am

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

Snowbird · May 30, 2022, 9:26am

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?

HongDa · June 6, 2022, 2:11am

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

Snowbird · June 6, 2022, 2:41am

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.

HongDa · June 6, 2022, 2:45am

The relevant range_id can be obtained by doing this:
https://suttacentral.net/api/suttas/an1.1

Snowbird · June 6, 2022, 4:24am

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.

Snowbird · August 3, 2022, 10:25am

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

sabbamitta · August 3, 2022, 11:37am

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

Snowbird · August 3, 2022, 11:58am

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.

sabbamitta · August 3, 2022, 12:44pm

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.

HongDa · August 13, 2022, 5:32am

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

Snowbird · August 13, 2022, 6:53am

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!

Khemarato.bhikkhu · August 3, 2023, 2:19am

What’s the correct API to use for getting the list of parallels, @HongDa ?

HongDa · August 3, 2023, 2:49am

Ven @Khemarato.bhikkhu , you can try this API:
https://suttacentral.net/api/parallels/mn1

API documentation question

Basic sutta content

SutaPlex

Menu

Publication info

Misc