Quick Start Guide

This guide will help you get started with the YouVersion Bible Client in just a few minutes.

Prerequisites

Before you begin, make sure you have:

  1. Python 3.9 or higher installed

  2. YouVersion account credentials

  3. The package installed (see Installation)

Setting Up Credentials

Create a .env file in your project root:

YOUVERSION_USERNAME=your_username
YOUVERSION_PASSWORD=your_password

Or set environment variables:

export YOUVERSION_USERNAME="your_username"
export YOUVERSION_PASSWORD="your_password"

Your First Script

Create a file named example.py:

Asynchronous Example

import asyncio
from youversion.clients import AsyncClient

async def main():
    async with AsyncClient() as client:
        # Get verse of the day
        votd = await client.verse_of_the_day()
        print(f"📖 Verse of the Day (Day {votd.day})")
        print(f"Reference: {votd.usfm}")

        # Get highlights
        highlights = await client.highlights(page=1)
        print(f"\n✨ Found {len(highlights)} highlights")

        # Get notes
        notes = await client.notes(page=1)
        print(f"📝 Found {len(notes)} notes")

if __name__ == "__main__":
    asyncio.run(main())

Synchronous Example

from youversion.clients import SyncClient

with SyncClient() as client:
    # Get verse of the day
    votd = client.verse_of_the_day()
    print(f"📖 Verse of the Day (Day {votd.day})")
    print(f"Reference: {votd.usfm}")

    # Get highlights
    highlights = client.highlights(page=1)
    print(f"\n✨ Found {len(highlights)} highlights")

    # Get notes
    notes = client.notes(page=1)
    print(f"📝 Found {len(notes)} notes")

Run Your Script

python example.py

Common Operations

Getting Moments

Moments are user-generated content including highlights, notes, bookmarks, images, and badges.

from youversion.clients import SyncClient

with SyncClient() as client:
    # Get all moments
    moments = client.moments(page=1)

    # Get specific types
    highlights = client.highlights(page=1)
    notes = client.notes(page=1)
    bookmarks = client.bookmarks(page=1)
    images = client.my_images(page=1)
    badges = client.badges(page=1)

    # Access moment properties
    for moment in moments:
        print(f"ID: {moment.id}")
        print(f"Title: {moment.moment_title}")
        print(f"Kind: {moment.kind_id}")

Searching the Bible

from youversion.clients import SyncClient

with SyncClient() as client:
    # Search Bible text
    results = client.search_bible("love", version_id=1)

    # Get Bible chapter
    chapter = client.get_bible_chapter("GEN.1", version_id=1)

    # Get Bible versions
    versions = client.get_bible_versions("eng", "all")

Working with Reading Plans

from youversion.clients import SyncClient

with SyncClient() as client:
    # Get plan progress
    progress = client.plan_progress(page=1)

    # Get plan subscriptions
    subscriptions = client.plan_subscriptions(page=1)

    # Get completed plans
    completions = client.plan_completions(page=1)

    # Search plans
    plans = client.search_plans("daily", language_tag="en")

Creating Moments

from youversion.clients import SyncClient
from youversion.models.moments import CreateMoment, ReferenceCreate
from youversion.enums import MomentKinds, StatusEnum

with SyncClient() as client:
    # Create a note
    moment_data = CreateMoment(
        kind=MomentKinds.NOTE,
        content="This is my study note",
        title="My Note",
        references=[
            ReferenceCreate(
                version_id=1,
                human="John 3:16",
                usfm=["JHN.3.16"]
            )
        ],
        status=StatusEnum.PRIVATE,
        body="This is my study note",
        color="ff0000",
        labels=["study"],
        language_tag="en"
    )

    result = client.create_moment(moment_data)
    print(f"Created moment: {result}")

Next Steps