REST Api

Table of Contents

• REST API
  • General structure of API calls
  • General structure of resulting data
  • Verbs
    • query
    • verse
• Deep linking to SHEBANQ
  • passages
• Contact

REST API

SHEBANQ has a REST API by which you can get specific data out of SHEBANQ in JSON format.

General structure of API calls

All API calls have the form:

https://shebanq.ancient-data.org/verb.json?param1=value1&param2=value2...

What parameters to use is dependent on the verb.

General structure of resulting data

All methods return a JSON dictionary containing the following entries:

key	value
good	A boolean stating whether the call was successful
msgs	A list of diagnostic messages. Every message is a pair consisting of a label indicating the kind of diagnostic (error, warning, info) and the text of the message
data	A dictionary or list of the actual data, depending on the specific verb

Verbs

query

Example: https://shebanq.ancient-data.org/hebrew/query.json?id=500

Returns the metadata of a query. There is a version independent part and a version dependent part (ETCBC data versions, that is). The metadata shows the number of results (per version), the query body, the execution status (whether the current results match the current body), the provenance, the version of the query engine, and more.

Parameters:

param	value
id	id of the query whose data is to be fetched
iid	synonymous to id

verse

Example: https://shebanq.ancient-data.org/hebrew/verse.json?version=4b&book=Genesis&chapter=1&verse=1

Returns the text of a verse, specified by book, chapter number and verse number. The text is returned in two ways:

repr	description
text	plain Hebrew text, Unicode, pointed, accented, as in a printed version of the BHS
phonetic	phonetic transcription, generated by the phono tool

Parameters:

param	value
version	version of the ETCBC data (4, 4b, ...)
book	name of the bible book, spelled exactly as in SHEBANQ
chapter	chapter number
verse	verse number

Deep linking to SHEBANQ

You can deep-link to certain items of data in SHEBANQ. These links are provided in the cite drawer in the lower-right corner of the screen.

Here we highlight some less obvious ways of deep-linking to material.

passages

Example: https://shebanq.ancient-data.org/hebrew/text?version=4b&book=Genesis&chapter=1&verse=11&mr=m&tr=ph&tp=txt_tb1&nget=v

This is how you get text from SHEBANQ. Shows a specified verse in the context of a whole chapter. The verse is softly highlighted and scrolled to. It is possible to specify alternative ways for viewing the text, such as phonetic view or notes view.

Parameters:

param	value
version	version of the ETCBC data (4, 4b, ...)
book	name of the bible book, spelled exactly as in SHEBANQ
chapter	chapter number
verse	verse number
mr	should be m, no choice here;
tr	either hb (Hebrew text) or ph (phonetic text)
tp	txt_p (plain text) or txt_tb1 (notes view) or txt_tb2 (syntax view) or txt_tb3 (abstract view)
nget	only relevant if tp=txt_tb1 (notes view). If nget=v, all notes will be prefetched and shown. If it is x, nodes will not be fetched initially, but the user can fetch them later as needed.

highlighted lexeme within passage

Example: lexeme FJM[ https://shebanq.ancient-data.org/hebrew/text?version=4b&c_w1FJMv=spring&mr=m&wget=v&wactive=hlcustom&book=Numeri&chapter=6&verse=26&tr=hb&tp=txt_p&nget=x

This shows the specified verse in the context of a whole chapter with all occurrences of the specified lexeme highlighted. The verse is softly highlighted and scrolled to.

Parameters:

param	value
version	version of the ETCBC data (4, 4b, ...)
c_wid	where id is the id of the lexeme in question (see below). The value should be a colour, such as spring. See the colour pickers in SHEBANQ for the available colours.
mr	should be m, no choice here;
wget	should be v, no choice here;
wactive	should be hlcustom, no choice here;
book	name of the bible book, spelled exactly as in SHEBANQ, when the Latin language has been chosen for the display of book names
chapter	chapter number
verse	verse number
tr	either hb (Hebrew text) or ph (phonetic text)
tp	txt_p (plain text) or txt_tb1 (notes view) or txt_tb2 (synatx view) or txt_tb3 (abstract view)
nget	only relevant if tp=txt_tb1 (notes view). If nget=v, all notes will be prefetched and shown. If it is x, nodes will not be fetched initially, but the user can fetch them later as needed.

Note The id of a lexeme can be found by looking up the lexeme in SHEBANQ, and citing it. You can also transform the lexeme to get the id by applying the following rules:

• the lexeme id has the shape: 1translit or 2translit where
  • 1 is used for Hebrew words and
  • 2 for Aramaic words;
• translit is the ETCBC transliteration of the lexeme, including disambiguation marks, with the following transformations:
  • the > is an aleph, replace it by A
  • the < is an ayin, replace it by O
  • the / denotes a noun, replace it by n
  • the [ denotes a verb, replace it by v
  • the = is for disambiguation, replace it by i

Note on the parameter mr. The method text() is a fairly low level function. It can also be used for retrieving result lists of verses, for queries or lexemes. In these cases mr=r. But you will not see this, because the methods query() and word() take care of this. These methods call text() with suitable parameters.

Contact

Interested in integrating data from SHEBANQ in your application or website but seeing no verb that suits you? Having issues? Please contact me, I'm willing to extend the API or to have a look.

shebanq@ancient-data.org.