Passage HTML Endpoint

Our passage HTML endpoint, located at /v3/passage/html/, provides passages from the ESV in HTML. The rendering of the text is customizable through optional parameters.

Example Request and Response

A simple request using cURL would look like this:

curl -H 'Authorization: Token YOUR_API_KEY' 'https://api.esv.org/v3/passage/html/?q=John+11:35'

You will receive a JSON response containing ESV text and metadata about the passage you requested:

{
  "query": "John 11:35",
  "canonical": "John 11:35",
  "parsed": [
    [
      43011035,
      43011035
    ]
  ],
  "passage_meta": [
    {
      "canonical": "John 11:35",
      "chapter_start": [
        43011001,
        43011057
      ],
      "chapter_end": [
        43011001,
        43011057
      ],
      "prev_verse": 43011034,
      "next_verse": 43011036,
      "prev_chapter": [
        43010001,
        43010042
      ],
      "next_chapter": [
        43012001,
        43012050
      ]
    }
  ],
  "passages": [
        "<h2 class=\"extra_text\">John 11:35 <small class=\"audio extra_text\">(<a class=\"mp3link\" href=\"https://audio.esv.org/hw/43011035-43011035.mp3\" title=\"John 11:35\" type=\"audio/mpeg\">Listen</a>)</small></h2>\n<p id=\"p43011035_01-1\" class=\"virtual\"><b class=\"verse-num\" id=\"v43011035-1\">35 </b>Jesus wept.</p>\n<p>(<a href=\"http://www.esv.org\" class=\"copyright\">ESV</a>)</p>"
  ]
}

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

Optional Parameters

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.

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