ESV API Sample Projects

The following sample projects are implemented in Python 3 and are intended to be run on the command line:

• Passage Lookup
• Random Proverb
• Reading Plan

Passage Lookup

This project takes a passage reference and returns the ESV text for that passage.

#!/usr/bin/env python

import sys
import requests


API_KEY = 'YOUR_API_KEY'
API_URL = 'https://api.esv.org/v3/passage/text/'


def get_esv_text(passage):
    params = {
        'q': passage,
        'include-headings': False,
        'include-footnotes': False,
        'include-verse-numbers': False,
        'include-short-copyright': False,
        'include-passage-references': False
    }

    headers = {
        'Authorization': 'Token %s' % API_KEY
    }

    response = requests.get(API_URL, params=params, headers=headers)

    passages = response.json()['passages']

    return passages[0].strip() if passages else 'Error: Passage not found'


if __name__ == '__main__':
    passage = ' '.join(sys.argv[1:])

    if passage:
        print(get_esv_text(passage))

---

Back to Top

Random Proverb

This project prints a random verse from the book of Proverbs.

#!/usr/bin/env python

import re
import random
import requests


API_KEY = 'YOUR_API_KEY'
API_URL = 'https://api.esv.org/v3/passage/text/'

CHAPTER_LENGTHS = [
    33, 22, 35, 27, 23, 35, 27, 36, 18, 32,
    31, 28, 25, 35, 33, 33, 28, 24, 29, 30,
    31, 29, 35, 34, 28, 28, 27, 28, 27, 33,
    31
]


def get_passage():
    chapter = random.randrange(1, len(CHAPTER_LENGTHS))
    verse = random.randint(1, CHAPTER_LENGTHS[chapter])

    return 'Proverbs %s:%s' % (chapter, verse)


def get_esv_text(passage):
    params = {
        'q': passage,
        'indent-poetry': False,
        'include-headings': False,
        'include-footnotes': False,
        'include-verse-numbers': False,
        'include-short-copyright': False,
        'include-passage-references': False
    }

    headers = {
        'Authorization': 'Token %s' % API_KEY
    }

    data = requests.get(API_URL, params=params, headers=headers).json()

    text = re.sub('\s+', ' ', data['passages'][0]).strip()

    return '%s – %s' % (text, data['canonical'])


def render_esv_text(data):
    text = re.sub('\s+', ' ', data['passages'][0]).strip()

    return '%s – %s' % (text, data['canonical'])


if __name__ == '__main__':
    print(get_esv_text(get_passage()))

---

Back to Top

Reading Plan

This project prints readings from the Book of Common Prayer for a given day. The user supplies a day number to the script.

Reading data is gathered from a JSON file, available here.

#!/usr/bin/env python

import sys
import json
import requests


API_KEY = 'YOUR_API_KEY'
API_URL = 'https://api.esv.org/v3/passage/text/'


def exit_with_error(s):
    print('Error: %s' % s)

    exit()


def get_esv_text(passage):
    params = {
        'q': passage,
        'include-short-copyright': False,
    }

    headers = {
        'Authorization': 'Token %s' % API_KEY
    }

    response = requests.get(API_URL, params=params, headers=headers)

    return response.json()['passages']


def render_reading(name, passage):
    texts = get_esv_text(passage)

    print(name)
    print('-' * len(name))
    print(''.join(texts))


if __name__ == '__main__':
    if len(sys.argv) < 2:
        exit_with_error('Missing day number')

    day_number = sys.argv[1]

    if not day_number.isdigit():
        exit_with_error('Invalid day number')

    day_number = int(day_number)

    entries = json.load(open('book-of-common-prayer.json'))

    if day_number < 1 or day_number > len(entries):
        exit_with_error('Day number out of range')

    for name, passage in entries[day_number - 1].items():
        render_reading(name, passage)

---

Back to Top