FhlBibleApi 1.1.0

FHL Bible API - C# SDK

A comprehensive .NET SDK for the FHL (Faith, Hope, Love) Bible API. Provides easy access to Chinese and English Bible translations, Strong's numbers, commentaries, and more.

Features

• 📖 Multiple Bible Versions: Access various Chinese and English translations
• 🔍 Powerful Search: Search by keywords, verses, or Strong's numbers
• 📚 Rich Metadata: Book information, chapter counts, and more
• 🔤 Strong's Dictionary: Look up original Hebrew and Greek words
• 📝 Word Parsing: Get grammatical analysis with Strong's numbers
• 📜 Apocrypha: Access to deuterocanonical books (次經, books 101-115)
• ✝️ Apostolic Fathers: Early Christian writings (使徒教父, books 201-217)
• 💬 Commentary: Chinese commentary and study notes (信望愛站註釋)
• 🌐 Simplified/Traditional Chinese: Support for both character sets
• ⚡ Async/Await: Modern async API with cancellation support
• 🧪 Well Tested: Comprehensive test coverage with NUnit (27+ tests)
• 💉 Dependency Injection: Built-in support for ASP.NET Core DI

Installation

dotnet add package FhlBibleApi

Or via NuGet Package Manager:

Install-Package FhlBibleApi

Quick Start

Basic Usage

using FhlBibleApi.Infrastructure;

// Create a client
var httpClient = new HttpClient();
var client = new FhlBibleApiClient(httpClient);

// Get a verse
var verses = await client.GetVerseAsync("John", 3, "16");
foreach (var verse in verses)
{
    Console.WriteLine($"{verse.Reference}: {verse.Text}");
}

// Search for verses
var results = await client.SearchAsync("love");
Console.WriteLine($"Found {results.TotalCount} verses");

ASP.NET Core Integration

using FhlBibleApi;

// In Program.cs or Startup.cs
builder.Services.AddFhlBibleApi(options =>
{
    options.UseSimplifiedChinese = false;  // Use traditional Chinese
    options.DefaultVersion = "unv";         // Default to 和合本
    options.TimeoutSeconds = 30;
});

// In your controller or service
public class BibleController : ControllerBase
{
    private readonly IFhlBibleApiClient _bibleApi;

    public BibleController(IFhlBibleApiClient bibleApi)
    {
        _bibleApi = bibleApi;
    }

    [HttpGet("verse/{book}/{chapter}/{verse}")]
    public async Task<IActionResult> GetVerse(string book, int chapter, string verse)
    {
        var verses = await _bibleApi.GetVerseAsync(book, chapter, verse);
        return Ok(verses);
    }
}

API Reference

Get Bible Books

// Get all books
var books = await client.GetBooksAsync();

// Get only Old Testament books
var otBooks = await client.GetBooksAsync(testament: "OT");

// Get only New Testament books
var ntBooks = await client.GetBooksAsync(testament: "NT");

// Get book information
var genesis = await client.GetBookInfoAsync("Gen");
Console.WriteLine($"{genesis.FullName} has {genesis.ChapterCount} chapters");

Get Verses

// Single verse
var verses = await client.GetVerseAsync("John", 3, "16");

// Multiple verses (range)
var verses = await client.GetVerseAsync("John", 3, "16-18");

// Multiple verses (comma-separated)
var verses = await client.GetVerseAsync("John", 3, "16,18,20");

// With different version
var verses = await client.GetVerseAsync("John", 3, "16", version: "kjv");

// With Strong's numbers
var verses = await client.GetVerseAsync("John", 1, "1", includeStrong: true);
foreach (var verse in verses)
{
    if (verse.StrongNumbers != null)
    {
        Console.WriteLine($"Strong's: {string.Join(", ", verse.StrongNumbers)}");
    }
}

Get Chapters

// Get entire chapter
var chapter = await client.GetChapterAsync("John", 3);
Console.WriteLine($"Chapter has {chapter.Verses.Count} verses");

// With specific version
var chapter = await client.GetChapterAsync("John", 3, version: "kjv");

Search

// Basic search
var results = await client.SearchAsync("love");
Console.WriteLine($"Found {results.TotalCount} verses containing 'love'");

// Search with version
var results = await client.SearchAsync("愛", version: "unv");

// Search in specific testament
var results = await client.SearchAsync("faith", testament: "NT");

// Pagination
var results = await client.SearchAsync("grace", limit: 10, offset: 0);

Strong's Numbers

// Look up Strong's number with prefix
var entry = await client.LookupStrongAsync("H430");  // Hebrew
var entry = await client.LookupStrongAsync("G3056"); // Greek

Console.WriteLine($"{entry.OriginalWord} ({entry.Transliteration})");
Console.WriteLine($"Definition: {entry.Definition}");
Console.WriteLine($"中文: {entry.ChineseDefinition}");

// Look up without prefix (must specify testament)
var entry = await client.LookupStrongAsync("430", testament: "OT");

// Search verses by Strong's number
var results = await client.SearchByStrongNumberAsync("G3056", testament: "NT");

Word Parsing (原文解析)

// Get word parsing with grammatical details
var parsing = await client.GetWordParsingAsync(43, 3, 16); // John 3:16

Console.WriteLine($"Found {parsing.RecordCount} words");
foreach (var word in parsing.Records.Where(w => w.StrongNumber != null))
{
    Console.WriteLine($"Word: {word.Word}");
    Console.WriteLine($"  Strong's: {word.StrongNumber}");
    Console.WriteLine($"  Part of Speech: {word.PartOfSpeech}");
    Console.WriteLine($"  Original Form: {word.OriginalForm}");
    Console.WriteLine($"  Meaning: {word.Explanation}");
}

Apocrypha (次經)

// Get verse from Apocrypha (books 101-115)
var verses = await client.GetApocryphaVerseAsync(101, 1, 10); // 1 Maccabees 1:10
Console.WriteLine($"{verses[0].Reference}: {verses[0].Text}");

// Get entire chapter from Apocrypha
var chapters = await client.GetApocryphaChapterAsync(101, 1);
Console.WriteLine($"Chapter has {chapters.Count} verses");

Apostolic Fathers (使徒教父)

// Get verse from Apostolic Fathers writings (books 201-217)
var verses = await client.GetApostolicFathersVerseAsync(201, 1, 1); // 1 Clement 1:1
Console.WriteLine($"{verses[0].Reference}: {verses[0].Text}");

// Get entire chapter
var chapters = await client.GetApostolicFathersChapterAsync(201, 1);
Console.WriteLine($"Chapter has {chapters.Count} verses");

Commentary (註釋)

// Get commentary for a specific verse
var commentary = await client.GetCommentaryAsync(1, 1, 9); // Genesis 1:9

foreach (var record in commentary.Records)
{
    Console.WriteLine($"Title: {record.Title}");
    Console.WriteLine($"Source: {record.BookName}");
    Console.WriteLine($"Commentary: {record.Text}");
}

// Navigate to previous/next commentary
if (commentary.PreviousVerse != null)
{
    Console.WriteLine($"Previous: {commentary.PreviousVerse.Reference}");
}
if (commentary.NextVerse != null)
{
    Console.WriteLine($"Next: {commentary.NextVerse.Reference}");
}

Bible Versions

// Get available versions
var versions = await client.GetVersionsAsync();
foreach (var version in versions)
{
    Console.WriteLine($"{version.Code}: {version.Name}");
    if (version.HasStrongNumbers)
    {
        Console.WriteLine("  (includes Strong's numbers)");
    }
}

Configuration Options

var options = new FhlBibleApiOptions
{
    BaseUrl = "https://bible.fhl.net/api",  // API base URL
    TimeoutSeconds = 30,                      // HTTP timeout
    UseSimplifiedChinese = false,             // true = 简体, false = 繁體
    DefaultVersion = "unv"                    // Default Bible version
};

var client = new FhlBibleApiClient(httpClient, options);

Common Bible Versions

Error Handling

try
{
    var verses = await client.GetVerseAsync("John", 3, "16");
}
catch (ArgumentException ex)
{
    // Invalid input parameters
    Console.WriteLine($"Invalid input: {ex.Message}");
}
catch (InvalidOperationException ex)
{
    // API request failed or response parsing error
    Console.WriteLine($"API error: {ex.Message}");
}
catch (HttpRequestException ex)
{
    // Network error
    Console.WriteLine($"Network error: {ex.Message}");
}

Examples

Example 1: Display John 3:16 in Multiple Versions

var versions = new[] { "unv", "kjv", "niv" };
foreach (var version in versions)
{
    var verses = await client.GetVerseAsync("John", 3, "16", version: version);
    Console.WriteLine($"\n{version.ToUpper()}:");
    Console.WriteLine(verses[0].Text);
}

Example 2: Search and Display Results

var results = await client.SearchAsync("faith hope love", limit: 5);
Console.WriteLine($"Top {results.Results.Count} of {results.TotalCount} results:\n");

foreach (var verse in results.Results)
{
    Console.WriteLine($"{verse.Reference}");
    Console.WriteLine($"  {verse.Text}");
    Console.WriteLine();
}

Example 3: Word Study with Strong's Numbers

// Look up the Greek word "logos" (λόγος)
var strong = await client.LookupStrongAsync("G3056");
Console.WriteLine($"Word: {strong.OriginalWord}");
Console.WriteLine($"Transliteration: {strong.Transliteration}");
Console.WriteLine($"Definition: {strong.Definition}");

// Find all verses using this word
var verses = await client.SearchByStrongNumberAsync("G3056", limit: 10);
Console.WriteLine($"\nFound in {verses.TotalCount} verses:");
foreach (var verse in verses.Results)
{
    Console.WriteLine($"  {verse.Reference}");
}

Requirements

• .NET 8.0 or later
• System.Net.Http.Json
• System.Text.Json

Development

Building

dotnet build

Running Tests

dotnet test

Publishing to NuGet

dotnet pack -c Release
dotnet nuget push bin/Release/FhlBibleApi.1.0.0.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• FHL (信望愛資訊中心) for providing the Bible API
• All contributors and testers

Support

• 📧 Email: support@fhl.net
• 🐛 Issues: GitHub Issues
• 📖 Documentation: API Docs

Roadmap

• Support for Apocrypha books
• Commentary and cross-reference APIs
• Audio Bible support
• Caching layer for improved performance
• Rate limiting support

Made with ❤️ for the Christian developer community