I mentioned last week that my Bible study set up using Ulysses was published over at The Sweet Setup earlier this month. This resulted in a handful of people asking about my reference to using the ESV API to populate Ulysses with Scripture.

I was (obviously) not quite clear in the article. It was my intention to start that a person could use the API. But I have not been doing that myself. Instead, I manually copy and paste 10 chapters at a time from the Bible Study app into Ulysses when needed. I do this for a couple reasons:

  • It’s easier to focus on my notes and highlights this way. I would have to go through the entire app to get my content out anyway (Olive Tree, like so many other companies, has not made it easy to get your data out), so I might as well include this in the migration process
  • Whether you copy and paste manually or use the API, there’s going to be some massaging of the content required

But since there were a few people curious about this, there may be some value in walking through how one could use the API.

Get a client

First, a disclaimer. I am no developer so there will likely be better ways to go about this. But I am technical enough to get content via an API 😀

The first step is to decide how you’re going to interact with the API. You can certainly make cURL requests from the command line … but that’s pretty neck beardy. When I have to work with an API, I prefer to use a graphical client. A coworker recommended Postman multiple times and it’s the best option I’m aware of.

Setting things up

Once you have that, you can head over to the ESV site and create yourself an account. From there, you need to create an “app” so you can get an access token to use in your API calls.

This needs to be included in the headers of each call, so no, you can’t skip it.

From there, you can head to the ESV API docs to figure out how to build your requests. There are a lot of options available, but for this purpose, you want a very minimal return to your response. Just the text and verses. You can set build your desired query right on their API page (click in the text boxes, then use the “Try It Out” button at the bottom.

It can take some twiddling and tweaking to get this just the way you want, but here’s a sample query of how I would use it:

https://api.esv.org/v3/passage/text/?q=ps1-10&include-passage-references=false&include-verse-numbers=true&include-footnotes=false&include-footnote-body=false&include-short-copyright=false&include-copyright=false&include-passage-horizontal-lines=false&include-heading-horizontal-lines=false&include-headings=true&include-selahs=true&indent-paragraphs=0&indent-poetry=false&indent-declares=0&indent-psalm-doxology=0&line-length=50

This is where Postman makes things pretty easy. You can simply copy and paste this URL into the GET request field at the top of the app.

Be sure to also include your authorization token in the Headers tab. It took me a bit to figure out how the ESV API wanted this to be formatted, but do not use the default options Postman provides. I set their authentication Type to No Authentication, then manually entered in the correct values in the headers.

Clean up

Once you have tested this a few times and you get the content that you want, you can run a query and then copy & paste the results into Ulysses. And this is where some clean up will be required.

If you have development chops, you could probably script up some solution for formatting the text as you want it (Regex, anyone?). The API does things like add square brackets to each verse number, so Ulysses treats them as links (see above). So it can take some time to get the content as you personally prefer it.

But at the very least, you can get what you need from the API. I hope that helps anyone who was considering this option!