API Documentation

Three gears on a red background symbolizing the API

Devotionalium.com offers a simple API (application programming interface). With this API website administrators can easily display the current Devotionalium on their own websites.

If you want to use Devotionalium with WordPress, you can simply use the official Devontionalium for WordPress Plugin.

Usage & Best Practices

The Devotionalium API is available free of charge. Please query it responsibly and for example try to use local caching instead of calling the API on every request to your site. Please also include a link to devotionalium.com somewhere on your site.

If you built something cool using Devotionalium, feel free to let me know.

The API currently uses no authentication scheme. You can access it via the url devotionalium.com/api.

To see an example implementation of an object-oriented way to access the API, you can refer to the official Devontionalium for WordPress Plugin.

API Endpoints

The API is accessible via the URL devotionalium.com/api/v2.

The following endpoints are availalbe:

Endpoint	Description
/api/v2	Retrieve Devotionalium data in JSON format
/api/v2/versions	List available Tanakh, Bible, and Quran versions
/api/v2/languages	List available language codes

Request

Request Parameters

The following parameters are available when retrieving Devotionalium via the /api/v2 endpoint.

You can transmit parameters to customize the response received. Parameters can be submitted either via GET as part of the URL or as POST request data.

Parameter	Required	Possible values	Description
lang	No	en-us (default), de-de	Use `/api/v2/languages` to get a list of available languages. The API will try to determine your language from your request headers as well.
bibleVersion	No	elb, kjv, lut …	The Tanakh version. Default depends on the chosen language. Use `/api/v2/versions` to get a list of available versions. See ScriptureVersion.id
bibleVersion	No	elb, kjv, lut …	The Bible version. Default depends on the chosen language. Use `/api/v2/versions` to get a list of available versions. See ScriptureVersion.id
quranVersion	No	orig, arberry, bubenheim …	The Quran version. Default depends on the chosen language. Use `/api/v2/versions` to get a list of available versions. See ScriptureVersion.id
date	No	Y-m-d	Which day's Devotionalium to return, e.g. 2019-04-01 for April 1st, 2019. If empty, will default to today (server time!).

Response

Possible Response Status Codes

Status code	Description
200	Request sucessful
400	Invalid request: See the response body for details
401	Not authenticated: You are accessing a resource you do not have permission for
500	A server error occurred during your request. Please report to hi@devotionalium.com if the issue persists

Response Structure

Parameter	Type	Description
0	ScriptureVerse	The first scripture verse.
1	ScriptureVerse	The second scripture verse.
2	ScriptureVerse	The third scripture verse.
date	String (Y-m-d)	The date of the scripture verses in format `Y-m-d`

Response Types

`ScriptureVerse`

Property	Type	Description
book	String	The human-readable book name for the piece of scripture.
bookNumber	Int	The logical id of the book
chapter	Int	The chapter the verse is part of
verses	Array[Int]	The verse numbers that are part of the verse
reference	String	The human-readable reference string of the scripture piece
referenceLong	String	A longer and more detailed variant of the reference
text	String	The text content of the scripture piece
textOriginal	String	The text content in the original language of the scripture
version	ScriptureVersion	The version information the text content is taken from
collectionName	String	The human-readable name of the collection the scripture piece belongs to (Tanakh, New Testament or Quran)
collection	Int	The collection id of the scripture piece
readingUrl	String	The canonical URL to the page where the entire context of the scripture piece can be read
readingData	ReadingData	Information about the expanded context reading belonging to the scripture piece. For internal use.
errors	Array[String]	A list of error messages that were generated while fetching the verse. This can have content if your selected version/translation does not contain the given verse.

`ScriptureVersion`

Property	Type	Description
id	String	The identifier of the version
name	String	The human-readable name of the version
language	String	The code of the language the version is written in
details	Array[String]	A list of human-readable additional version information. The available keys will be different for different collections

`ReadingData`

Property	Type	Description
bookNumber	Integer\|null	The book number of the extended reading
startChapter	Integer
endChapter	Integer\|null
startVerse	Integer\|null
endVerse	Integer\|null
highlight	String	The verses to be highlighted in the extended reading encoded as a string.

Sample Response

`GET https://devotionalium.com/api/v2?lang=en`

{
    "0": {
        "book": "Yĕsha‘ăyāhû",
        "bookNumber": 23,
        "chapter": 38,
        "verses": [
            "17"
        ],
        "text": "Behold, for peace I had great bitterness: but thou hast in love to my soul delivered it from the pit of corruption: for thou hast cast all my sins behind thy back.",
        "textOriginal": "הִנֵּה לְשָׁלוֹם מַר־לִי מָר וְאַתָּה חָשַׁקְתָּ נַפְשִׁי מִשַּׁחַת בְּלִי כִּי הִשְׁלַכְתָּ אַחֲרֵי גֵוְךָ כָּל־חֲטָאָי ׃",
        "version": {
            "id": "web",
            "name": "Webster",
            "language": "en",
            "details": {
                "description": "*",
                "publisher": "FREE BIBLE SOFWARE GROUP",
                "source": "ftp://unboundftp.biola.edu/pub/webster.zip"
            }
        },
        "collection": 0,
        "collectionName": "Tanakh",
        "reference": "Yĕsha‘ăyāhû 38:17",
        "referenceLong": "Yĕsha‘ăyāhû (Isaiah) 38:17",
        "readingUrl": "http://devotionalium.com/read/version/web/book/23/chapter/38",
        "errors": []
    },
    "1": {
        "book": "Romans",
        "bookNumber": 45,
        "chapter": 8,
        "verses": [
            "1"
        ],
        "text": "There is therefore now no condemnation to them who are in Christ Jesus, who walk not according to the flesh, but according to the Spirit.",
        "textOriginal": "Οὐδὲν ἄρα νῦν κατάκριμα τοῖς ἐν Χριστῷ Ἰησοῦ·",
        "version": {
            "id": "web",
            "name": "Webster",
            "language": "en",
            "details": {
                "description": "*",
                "publisher": "FREE BIBLE SOFWARE GROUP",
                "source": "ftp://unboundftp.biola.edu/pub/webster.zip"
            }
        },
        "collection": 1,
        "collectionName": "New Testament",
        "reference": "Romans 8:1",
        "referenceLong": "Romans 8:1",
        "readingUrl": "http://devotionalium.com/read/version/web/book/45/chapter/8",
        "readingData": {
            "bookNumber": 45,
            "startChapter": 8,
            "endChapter": 8,
            "startVerse": 1,
            "endVerse": null,
            "highlight": "8:1"
        },
        "errors": []
    },
    "2": {
        "book": "",
        "bookNumber": null,
        "chapter": 18,
        "verses": [
            "23"
        ],
        "text": "And do not say, regarding anything, 'I am going to do that tomorrow,'",
        "textOriginal": "وَلَا تَقُولَنَّ لِشَيْءٍ إِنِّي فَاعِلٌ ذَٰلِكَ غَدًا",
        "version": {
            "id": "arberry",
            "name": "A. J. Arberry",
            "language": "en",
            "details": {
                "writer": "A. J. Arberry",
                "language": "English",
                "source": "qurandatabase.org"
            }
        },
        "collection": 2,
        "collectionName": "Quran",
        "reference": "Al-Kahf 23",
        "referenceLong": "Al-Kahf (Surah 18) 23",
        "readingUrl": "http://devotionalium.com/read/version/arberry/book//chapter/18",
        "readingData": {
            "bookNumber": null,
            "startChapter": 18,
            "endChapter": 18,
            "startVerse": 1,
            "endVerse": null,
            "highlight": "18:23"
        },
        "errors": []
    },
    "date": "2019-08-03"
}