Build a C#/.NET Insight App: Astrology, Vedic, Tarot

The RoxyAPI .NET SDK ships on NuGet as RoxyApi.Sdk, the fourth typed client in the family after TypeScript, Python, and PHP. One install gives any ASP.NET Core, Blazor, MAUI, or Unity project the full surface: Western astrology, Vedic astrology, numerology, tarot, human design, forecast, biorhythm, I Ching, crystals, dreams, angel numbers, and location, plus usage and language helpers. The client is generated from the live OpenAPI spec, so every response is a fully typed object your IDE autocompletes, and new endpoints appear the day they ship. This post is a hands-on tutorial: by the end you will have a small ASP.NET Core app calling multiple RoxyAPI domains and returning JSON ready for any frontend.

What does the RoxyAPI .NET SDK cover, and why C#

RoxyApi.Sdk covers 164 endpoints across 12 insight domains under one API key, exposed as a strongly typed client in the RoxyApi namespace with RoxyClient as the entry point. C# runs a large share of enterprise backends, Unity games, and Blazor apps, and none of those stacks had a first-class typed insight client until now. The SDK is generated with Microsoft Kiota from the public OpenAPI specification, so the method tree mirrors the URL path exactly and the compiler catches a wrong field before you deploy. The only runtime dependency is Microsoft.Kiota.Bundle, MIT licensed and maintained by Microsoft.

Ready to build with this? The Vedic Astrology API and every other domain run under one key, every domain in every plan. See pricing.

How to install the .NET SDK and make your first call

Add the package with dotnet add package RoxyApi.Sdk, then construct one RoxyClient with your API key. The constructor sets the base URL (https://roxyapi.com/api/v2) and injects the auth header on every request, so application code never builds an HttpClient by hand. Read the key from configuration or an environment variable, never a literal. The daily horoscope is the simplest call in the catalog, no coordinates and no request body, just a lowercase sign on the path indexer.

dotnet add package RoxyApi.Sdk

using RoxyApi;

var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);

var horoscope = await roxy.Astrology.Horoscope["aries"].Daily.GetAsync();
Console.WriteLine(horoscope!.Overview);
Console.WriteLine($"Lucky number: {horoscope.LuckyNumber}, energy: {horoscope.EnergyRating}/10");

Running that against a live key today prints a real transit-driven reading:

Saturn steadies Aries with quiet determination today. Structure creates freedom, and
the boundaries you set now protect what matters most. Rest and reflect.
Lucky number: 28, energy: 9/10

Every call is async and returns the typed response directly, or throws RoxyError on a 4xx or 5xx. There is no result-wrapper object to unpack. The success body is nullable because errors throw, so use horoscope!.Overview or a null check after handling errors.

How to geocode a birth city and generate a Vedic kundli

Every chart, kundli, panchang, dasha, dosha, navamsa, KP, synastry, and natal endpoint needs Latitude, Longitude, and Timezone. Never ask a user to type coordinates. Call roxy.Location.Search first, take the first city, and pass its fields straight into the chart method. The Timezone field is a typed union, so wrap the IANA string with new() { String = city.Timezone } or a decimal offset with new() { Double = 5.5 }. The server resolves an IANA name to the DST-correct offset for the chart date, so a historical birth returns the right offset without caller-side date math.

using RoxyApi;
using RoxyApi.Models;
using Microsoft.Kiota.Abstractions; // Date and Time structs

var search = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "Mumbai");
var city = search!.Cities![0];

var kundli = await roxy.VedicAstrology.BirthChart.PostAsync(new()
{
    Date = new Date(1990, 1, 15),
    Time = new Time(14, 30, 0),
    Latitude = city.Latitude,
    Longitude = city.Longitude,
    Timezone = new() { String = city.Timezone },
});

foreach (var graha in kundli!.Leo!.Signs ?? [])
    Console.WriteLine($"{graha.Graha} in Leo, house {graha.House}: " +
        $"{graha.Nakshatra?.Name} pada {graha.Nakshatra?.Pada}");

The Vedic response is where the depth lives. Each sign accessor (kundli.Leo, kundli.Aries) carries a Signs list, and each entry exposes Graha, House, IsRetrograde, Longitude, and a Nakshatra object with Name, Pada, and Lord. The run above prints Moon in Leo, house 4: Purva Phalguni pada 3 for that birth, pada-quarter precision straight off the typed object with no manual longitude math.

How to combine domains in a single multi-insight call

Multi-domain readings are the unlock single-purpose APIs cannot match. Once the client is wired, a numerology Life Path, a daily tarot card, and a Western natal chart for the same user are three method calls on the same roxy instance. Because the three are independent, fire them together with Task.WhenAll so the whole profile resolves in one round trip of latency instead of three sequential ones. Each domain hangs off a property on the client, each method maps to one operationId in the spec, and each response is a typed object.

var search = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "Austin");
var city = search!.Cities![0];

var lifePathTask = roxy.Numerology.LifePath.PostAsync(new() { Year = 1990, Month = 1, Day = 15 });
var cardTask     = roxy.Tarot.Daily.PostAsync(new() { Seed = "user-42" });
var chartTask    = roxy.Astrology.NatalChart.PostAsync(new()
{
    Date = new Date(1990, 1, 15),
    Time = new Time(14, 30, 0),
    Latitude = city.Latitude,
    Longitude = city.Longitude,
    Timezone = new() { String = city.Timezone },
});
await Task.WhenAll(lifePathTask, cardTask, chartTask);

var lifePath = lifePathTask.Result;
var card = cardTask.Result;
var chart = chartTask.Result;

Console.WriteLine($"Life Path {lifePath!.Number}: {lifePath.Meaning?.Title}");
Console.WriteLine($"Card: {card!.Card!.Name}{(card.Card.Reversed == true ? " (reversed)" : "")}");
Console.WriteLine($"Ascendant: {chart!.Ascendant!.Sign}, element: {chart.Summary?.DominantElement}");

For that input the live API returns Life Path 8 titled "The Powerhouse", a natal Ascendant in Gemini, and a Summary.DominantElement of Earth. Nested fields are typed objects, not strings: chart.Ascendant has Sign, Degree, and Longitude, so drill in with chart.Ascendant.Sign. IntelliSense shows every field, and you rarely name a response type yourself, capture with var and let the compiler carry the shape.

How to wire the SDK into ASP.NET Core with dependency injection

RoxyClient is thread-safe and built once per process, so register it as a singleton in the DI container and inject it into any minimal-API handler, controller, or BackgroundService. Read the key from IConfiguration (user secrets in development, environment variables in production) rather than a literal. The pattern below is a complete two-endpoint app: a daily horoscope by sign and a natal chart that geocodes the city server-side, with RoxyError mapped to the matching HTTP status.

using RoxyApi;
using RoxyApi.Models;
using Microsoft.Kiota.Abstractions;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton(new RoxyClient(builder.Configuration["RoxyApi:Key"]
    ?? throw new InvalidOperationException("RoxyApi:Key is not configured.")));

var app = builder.Build();

app.MapGet("/api/horoscope/{sign}", async (string sign, RoxyClient roxy) =>
    Results.Ok(await roxy.Astrology.Horoscope[sign.ToLowerInvariant()].Daily.GetAsync()));

app.MapGet("/api/natal-chart", async (string city, string date, string time, RoxyClient roxy) =>
{
    try
    {
        var search = await roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = city);
        var loc = search!.Cities![0];
        var d = DateOnly.Parse(date);
        var t = TimeOnly.Parse(time);

        return Results.Ok(await roxy.Astrology.NatalChart.PostAsync(new()
        {
            Date = new Date(d.Year, d.Month, d.Day),
            Time = new Time(t.Hour, t.Minute, t.Second),
            Latitude = loc.Latitude,
            Longitude = loc.Longitude,
            Timezone = new() { String = loc.Timezone },
        }));
    }
    catch (RoxyError e)
    {
        return Results.Json(new { error = e.Message, code = e.Code }, statusCode: e.ResponseStatusCode);
    }
});

app.Run();

Never expose the API key in a Blazor WebAssembly, MAUI, Unity, or browser client. Call Roxy from server-side code only. The full SDK guide covers the same singleton pattern for controllers and hosted services.

How to localize responses and handle errors correctly

Two .NET-specific shapes are worth learning here. First, the Lang query parameter is a generated enum, not a string, so the compiler steers you to a valid value: pass PostLangQueryParameterType.Es, not "es". Interpretations are available in eight languages (en, tr, de, es, fr, hi, pt, ru), professionally localized and native-speaker reviewed. Second, every endpoint throws a typed RoxyError on failure, so switch on the stable Code, never the human-readable Message.

var card = await roxy.Tarot.Daily.PostAsync(
    new() { Seed = "user-42" },
    c => c.QueryParameters.Lang = RoxyApi.Tarot.Daily.PostLangQueryParameterType.Es);
Console.WriteLine($"{card!.Card!.Name}: {card.DailyMessage}");

That call returns Spanish interpretation text live: Reina de Bastos: Tu carta para 2026-07-08: Reina de Bastos (invertida). enfoque interior, reconstruir la autoestima, introversion, celos. Untranslated fields fall back to English. On the error path, RoxyError extends ApiException and exposes Code (stable, switch on it), Message (wording may change), ResponseStatusCode (the HTTP status), and Issues (every field that failed validation on a 400). Wrap calls in try { ... } catch (RoxyError e) and branch on e.Code: validation_error, invalid_api_key, subscription_inactive, rate_limit_exceeded, not_found, or internal_error. Explore any endpoint on the live API reference playground, which returns real production responses.

FAQ

How do I add astrology to a C# or .NET project?

Install the SDK with dotnet add package RoxyApi.Sdk and create a client with new RoxyClient(apiKey). The astrology namespace exposes 33 endpoints, including roxy.Astrology.Horoscope["aries"].Daily.GetAsync() for a transit-driven daily horoscope and roxy.Astrology.NatalChart.PostAsync(...) for a full natal chart with planets, houses, and aspects. Every response is a fully typed object, so your IDE autocompletes each field and the compiler catches mistakes before you deploy.

Which .NET versions does the RoxyAPI SDK support?

RoxyApi.Sdk targets net8.0 and netstandard2.0, so it runs on .NET 8 and later plus anything that consumes netstandard2.0: .NET Framework 4.6.1+, Unity, Xamarin, MAUI, Blazor, and Mono. Language version 12 or later is recommended for the target-typed new() and collection-expression syntax in the examples. The only runtime dependency is the MIT-licensed Kiota bundle from Microsoft.

How do I generate a Vedic kundli in C#?

Geocode the birth city with roxy.Location.Search.GetAsync(c => c.QueryParameters.Q = "Mumbai"), then call roxy.VedicAstrology.BirthChart.PostAsync(new() { Date = new Date(1990, 1, 15), Time = new Time(14, 30, 0), Latitude = city.Latitude, Longitude = city.Longitude, Timezone = new() { String = city.Timezone } }). Each sign accessor carries a Signs list where every planet exposes Graha, House, IsRetrograde, and a Nakshatra object with name and pada for pada-quarter precision.

Do RoxyAPI SDK calls return an error object or throw?

They throw. On success a call returns the typed response as a nullable reference; on a 4xx or 5xx it throws RoxyError, a subclass of ApiException. Wrap calls in try { ... } catch (RoxyError e) and switch on the stable e.Code. A 400 populates e.Issues with every field that failed validation, and e.ResponseStatusCode carries the HTTP status for mapping to your own responses.

How do I set the response language in the .NET SDK?

The Lang query parameter is a generated enum, not a string, so pass roxy.Tarot.Daily.PostAsync(new() { Seed = "user-42" }, c => c.QueryParameters.Lang = RoxyApi.Tarot.Daily.PostLangQueryParameterType.Es). Eight languages are supported (en, tr, de, es, fr, hi, pt, ru) across astrology, Vedic astrology, numerology, tarot, biorhythm, I Ching, crystals, and angel numbers. Untranslated fields fall back to English, and roxy.Languages.GetAsync() returns the live list.

Conclusion

The .NET SDK closes the C# gap in the RoxyAPI client family, which now spans TypeScript, Python, PHP, C#, and Go, all sharing the same operationId-driven surface across 164 endpoints and 12 domains under one key. Install with dotnet add package RoxyApi.Sdk, set your key in configuration, and ship an ASP.NET Core, Blazor, MAUI, or Unity insight app this afternoon. Start with the astrology API to grab a key and make your first call.