TripleG3.YouVersion 1.0.2

TripleG3.YouVersion

A strongly typed .NET client package for the YouVersion v1 REST API with dependency injection support.

Features

• Strong request/response models for YouVersion endpoints.
• Enums and constants for predictable parameter selection.
• Async API methods returning strongly typed .NET models.
• IServiceCollection extensions for API key, timeout, cache, and HttpClient registration.
• A complete Verse of the Day workflow that resolves and normalizes passage text.

Supported endpoints

• GET /verse_of_the_days/{day_of_year}
• GET /bibles/{bible_id}/passages/{passage_id}
• GET /bibles?language_ranges[]={language_range}
• GET /bibles/{bible_id}
• GET /bibles/{bible_id}/books
• GET /bibles/{bible_id}/books/{book_usfm}
• GET /bibles/{bible_id}/books/{book_usfm}/chapters
• GET /bibles/{bible_id}/books/{book_usfm}/chapters/{chapter_number}/verses
• GET /highlights

Install

dotnet add package TripleG3.YouVersion

Configure and use

The client reads YOUVERSION_API_KEY first and falls back to LIGHTHOUSE_YOUVERSION_API_KEY. It reads the optional default Bible ID from YOUVERSION_BIBLE_ID; otherwise, Bible ID 206 is used.

$env:YOUVERSION_API_KEY = "YOUR_API_KEY"
$env:YOUVERSION_BIBLE_ID = "206"

using Microsoft.Extensions.DependencyInjection;
using TripleG3.YouVersion.Abstractions;
using TripleG3.YouVersion.Extensions;
using TripleG3.YouVersion.Requests;

var services = new ServiceCollection();
services.AddYouVersionClient();

using var provider = services.BuildServiceProvider();
var client = provider.GetRequiredService<IYouVersionClient>();

var verseOfDay = await client.GetVerseOfDayAsync();
var bibles = await client.GetBiblesAsync(new GetBiblesRequest(["en"]));

if (verseOfDay.Available)
{
    Console.WriteLine($"{verseOfDay.Reference}: {verseOfDay.Content}");
}

By default, GetVerseOfDayAsync uses the current local calendar date and the configured Bible ID. A date or Bible can be selected explicitly:

var verseOfDay = await client.GetVerseOfDayAsync(
    new GetVerseOfDayRequest(
        Date: new DateOnly(2026, 7, 25),
        BibleId: 206));

The client calls GET /verse_of_the_days/{dayOfYear}, URL-encodes its passage_id, and then calls the text passage endpoint with headings and notes disabled. Passage whitespace is collapsed before VerseOfDayResult is returned.

Successful results are cached in process by date and Bible ID. The default connect and request timeouts are four and six seconds. Non-success responses or a missing passage ID return Available = false and Content = "Unavailable". If a passage has no content, Content falls back to its reference and then its passage ID.

Manual integration tests

Live endpoint tests are in TripleG3.YouVersion.IntegrationTests. The manual runner reads YOUVERSION_API_KEY from the ignored TripleG3.YouVersion/.env file and supplies it only to the test process. The tests are skipped during ordinary test runs and in CI.

Run them explicitly from PowerShell:

.\Invoke-YouVersionIntegrationTests.ps1

Version 2 migration

Version 2 targets https://api.youversion.com/v1/ and sends API keys with X-YVP-App-Key. It replaces the legacy verse_of_the_day call and embedded verse/image models with the two-call workflow and VerseOfDayResult, exposes GetPassageTextAsync, requires language ranges when listing Bibles, and uses integer Bible IDs. The unsupported Verse of the Day page, Versions, and Highlights APIs have been removed; Highlights requires a user Bearer token and is outside this app-key client.

Attribution

Provided by: YouVersion

• Website: https://www.youversion.com/
• API documentation: https://developers.youversion.com/api/data-exchange

All API content and rights belong to YouVersion.