TripleG3.YouVersion 1.0.4

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 operations

Install

dotnet add package TripleG3.YouVersion

Configure and use

The client targets https://api.youversion.com/v1/ and sends the required X-YVP-App-Key header from YOUVERSION_API_KEY. Consumers must supply that environment variable or set YouVersionOptions.ApiKey directly. The optional YOUVERSION_BIBLE_ID environment variable changes the default 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"]));
var passage = await client.GetPassageTextAsync(206, "JHN.3.16");

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

GetBiblesAsync requires at least one language range. Bible IDs are integers, and passage IDs are URL-encoded by the client.

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.

Package readme

This root README.md is embedded as the NuGet package readme, so the same setup, usage, and migration guidance is displayed on the package page after publishing.

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.