Generating URL Scheme for YouVersion's Bible App using Pythonista

I use YouVersion's Bible app on a daily basis. It's the first app I open every morning. I usually end my Bible reading session by picking out a verse that hits home for me. Then, I store it in Momento, and cross-share it to Facebook and Twitter via Path.

As I was reading through Ben Tsai's website, I stumbled upon his post about YouVersion's Bible app URL Scheme. I didn't know that the app has any URL Scheme beyond the one shown in Launch Center Pro: youversion:.

Ben wrote about several undocumented URL Schemes that the app supports:

  • youversion://bible?reference=PHP.4.5+PHP.4.7
  • youversion://bookmarks
  • youversion://reading_plans

I was really excited with the possibility of storing/sharing a verse with a URL Scheme that could redirect me back straight to the verse. But, before I got to work, I realised that the app uses OSIS Book Abbreviations that requires me to have a Map/Dictionary stored somewhere for runtime lookup.

YouVersion's Bible app supports the selection of multiple verses and multiple verse ranges.

Converting the References to URL Schemes

YouVersion's Bible app allows you to select one or more verses within a single chapter, and put them into the clipboard. Here's an example of what the clipboard looks like if you select a single verse:

Guard your heart above all else, for it determines the course of your life. (Proverbs 4:23 NLT)

The first thing that came to mind was grabbing the (Proverbs 4:23 NLT) part using regular expression. I was using Patterns on the Mac and TextTool on iOS to tinker with it. Craig Pearlman, TextTool's developer, even helped me with my inadequate regular expression skills. But, I decided to go with Pythonista because I would need to convert the OSIS code as well.

Here's the final Pythonista script that I have:

I create a Dictionary to convert OSIS codes that do not follow the three-letter initial pattern. The script can also handle cases that involve more than one verse, such as:

Genesis 1:1-3
Genesis 1:20, 22-24
Genesis 1:18-20, 25
Genesis 1:1-3, 5-7, 9-11, 13, 14

To handle verse ranges, I convert each range to enumeration instead. For example, I convert 1-3 to 1,2,3. After all, that's how YouVersion's Bible URL Scheme is defined. After a few tests, the app can really show these verses, even though some of them will be skipped from the clipping.

Once the verses are ready, I construct their references in BOOK.Chapter.Verse format. I send it as an argument to the YouVersion's Bible URL Scheme.

I collect these notes in 1Writer as I listen to the sermon, and send it to Day One once the sermon is over.

My Use Cases

Now, I have set up four use cases on how I would use this reference:

  1. Store my verse of the day in Markdown format in Day One
  2. Append verses as I take sermon notes in a local file named "Sermon" in 1Writer
  3. Send the verse and the URL as an iMessage and return to the Bible app
  4. Send only the URL as an iMessage and return to the Bible app

And, I have set up a Launch Center Pro action to prompt me which mode I'd like to process the verse in.

Open this link to automatically install this action on Launch Center Pro. You're welcome to change the Pythonista script and Launch Center Pro action to suit your needs.


This example shows that supporting URL Schemes enables new use cases that may not have been considered by the developers when designing the app. I have tested the script to take notes during the sermon I attended this morning, and I like the result. It's now easier for me to switch between YouVersion's Bible and 1Writer during the sermon, and store it to Day One once the sermon is over. If you have any questions regarding the script or any other use cases that you'd like me to help, let me know via Twitter.

You should follow me on Twitter here.