ESV API Overview

The ESV API provides access to the ESV text, with a customizable presentation in multiple formats. You will need an HTTP client in your programming language of choice to use the API.

To obtain an API key, you will first need to create an API Application.

Authorization

When making requests, you will need to include your application's key with each request in the Authorization header like this:

Authorization: Token {{ YOUR_KEY }}

Endpoints

We provide the following API endpoints:

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

These endpoints support many optional parameters, but q (your passage query) is the only one that's required.

Example Requests

A simple request using cURL would look like this:

curl -H 'Authorization: Token {{ YOUR_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": [
    "\nJohn 11:35\n\n  [35] Jesus wept. (ESV)"
  ]
}

A request to the audio endpoint would look like this:

curl -L -H 'Authorization: Token {{ YOUR_KEY }}' 'https://api.esv.org/v3/passage/audio/?q=John+11:35' > audio.mp3

The audio endpoint returns a redirect to an MP3 file. Be sure that your client follows redirects when using this endpoint.

Optional Parameters

Our plain text and HTML endpoints accept many parameters that change the presentation of the ESV text in the passages key of the API response.

See our API Parameters page for details.

Sample Projects

We've created a few sample projects to help you get started with our API. Each is implemented in Python 3 and intended to be run on the command line.

See our API Sample Projects page for details.