Passage Text Endpoint

Our passage text endpoint, located at /v3/passage/text/, provides passages from the ESV in plain text. 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/text/?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": [
    "John 11:35\n\n  [35] Jesus wept. (ESV)"
  ]
}

---

Back to Top

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

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