ESV API Parameters

Below are the parameters available to our API endpoints:

  • /v3/passage/html/ for HTML
  • /v3/passage/text/ for plain text
  • /v3/passage/audio for audio files

We have broken them down into the following sections:

Required Parameters

Name: q
Type: string
Default: ''

This is the requested passage. We try our best to parse a meaningful passage reference from this value. Here are some examples of what's accepted:

  • John 1:1
  • jn11.35
  • Genesis 1-3
  • 43011035
  • 01001001-01011032
  • John1.1;Genesis1.1
  • 19001001-19001006,19003001-19003008

Back to Top

Parameters Common to the Plain Text and HTML Endpoints

Name: include-passage-references
Type: boolean
Default: true

Include the passage reference before the text.


Name: include-verse-numbers
Type: boolean
Default: true

Include verse numbers.


Name: include-first-verse-numbers
Type: boolean
Default: true

Include the verse number for the first verse of a chapter.


Name: include-footnotes
Type: boolean
Default: true

Include callouts to footnotes in the text.


Name: include-footnote-body
Type: boolean
Default: true

Include footnote bodies below the text. Only works if include-footnotes is also true.


Name: include-headings
Type: boolean
Default: true

Include section headings. For example, the section heading of Matthew 5 is "The Sermon on the Mount".


Name: include-short-copyright
Type: boolean
Default: true

Include "(ESV)" at the end of the text. Mutually exclusive with include-copyright. This fulfills your copyright display requirements.


Name: include-copyright
Type: boolean
Default: false

Include a copyright notice at the end of the text. Mutually exclusive with include-short-copyright. This fulfills your copyright display requirements.


Back to Top

HTML-Only Parameters

Name: include-css-link
Type: boolean
Default: false

Include a link tag that provides CSS for the returned text.


Name: inline-styles
Type: boolean
Default: false

Include inline CSS for the returned text.


Name: wrapping-div
Type: boolean
Default: false

Wrap the text in a div tag with feature classes applied.


Name: div-classes
Type: string
Default: passage

Add extra CSS classes to the wrapping div generated by the option above.


Name: paragraph-tag
Type: string
Default: p

Customize the HTML tag used for paragraph elements.


Name: include-book-titles
Type: boolean
Default: false

Include an h2 containing a book name if the first verse of a book is in the requested text.


Name: include-verse-anchors
Type: boolean
Default: false

Add an anchor tag at every verse and heading boundary containing embedded verse data.


Name: include-chapter-numbers
Type: boolean
Default: true

Include a chapter number if the first verse in a chapter is in the requested text.


Name: include-crossrefs
Type: boolean
Default: false

Include cross-reference call-outs in the text.


Name: include-subheadings
Type: boolean
Default: true

Include subheadings. Subheadings are the titles of psalms (e.g., Psalm 73's 'A Maskil of Asaph'), the acrostic divisions in Psalm 119, the speakers in Song of Solomon, and the textual notes that appear in John 7 and Mark 16.


Name: include-surrounding-chapters
Type: boolean
Default: false

Show links above the text to the previous, current (if not showing the whole chapter) and next chapters in the Bible. You can modify the link by changing the link-url parameter.


Name: include-surrounding-chapters-below
Type: string
Default: smart

Same as the include-surrounding-chapters parameter above, but the links are rendered below the text. This value may also be the string smart, in which case the links will be shown based on the include-surrounding-chapters parameter.


Name: include-surrounding-chapters-below-threshold
Type: integer
Default: 10

If include-surrounding-chapters-below is equal to smart, and include-surrounding-chapters is true, the minimum verse-length of the passage after which the trailing links are displayed. Must be an integer.


Name: link-url
Type: string
Default: ''

Where embedded links to other passages should point. Applies only when include-surrounding-chapters is set to true.


Name: crossref-url
Type: string
Default: ''

Where embedded cross reference links should point. Only applies if include-crossrefs is true.


Name: preface-url
Type: string
Default: https://www.esv.org/preface/

Where embedded links to the preface should point. Only applies if include-footnotes is true.


Name: include-audio-link
Type: boolean
Default: true

Include a link to the audio version of the requested passage. The link appears in a small tag in the passage's identifying h2 tag.


Name: attach-audio-link-to
Type: string
Default: passage

Which feature to attach the audio link to. Must be either passage or heading.


Back to Top

Plain Text-Only Parameters

Name: include-passage-horizontal-lines
Type: boolean
Default: false

Include a line of equal signs (====) above the beginning of each passage.


Name: include-heading-horizontal-lines
Type: boolean
Default: false

Include a visual line of underscores (____) above each section heading.


Name: horizontal-line-length
Type: integer
Default: 55

Controls the length of the line for include-passage-horizontal-lines and include-heading-horizontal-lines.


Name: include-selahs
Type: boolean
Default: true

Include "Selah" in certain Psalms.


Name: indent-using
Type: string
Default: space

Controls indentation. Must be space or tab.


Name: indent-paragraphs
Type: integer
Default: 2

Controls how many indentation characters start a paragraph.


Name: indent-poetry
Type: boolean
Default: true

Controls indentation of poetry lines.


Name: indent-poetry-lines
Type: integer
Default: 4

Controls how many indentation characters are used per indentation level for poetry lines.


Name: indent-declares
Type: integer
Default: 40

Controls how many indentation characters are used for "Declares the LORD" in some of the prophets.


Name: indent-psalm-doxology
Type: integer
Default: 30

Controls how many indentation characters are used for Psalm doxologies.


Name: line-length
Type: integer
Default: 0

Controls how long a line can be before it is wrapped. Use 0 for unlimited line lengths.


Back to Top