RoxyAPI MCP server

Astrology API SDK for Rust

RoxyAPI is the data layer for insight, belief and prediction products. The roxyapi crate brings asynchronous Rust access to Western and Vedic astrology, tarot, numerology, Human Design, and 18+ insight domains on one key.

Build natal charts, horoscopes, compatibility readings, and cross-domain forecasts with typed requests and responses. Astronomical positions are verified against NASA JPL Horizons. RoxyAPI also provides Remote MCP, UI components, Templates, localized interpretations, and flat all-inclusive pricing. See the methodology, API reference, and pricing.

Install

cargo add roxyapi
cargo add tokio --features macros,rt-multi-thread

Runs on the Tokio asynchronous runtime. Reuse a Roxy instance or clone it to share connections across handlers. Rust 1.88 or newer is required.

Start with one call

Get real product value with a single typed call. No setup beyond your API key.

use roxyapi::{Roxy, types};

# async fn run() -> Result<(), Box<dyn std::error::Error>> {
let roxy = Roxy::new(std::env::var("ROXY_API_KEY")?)?;
let horoscope = roxy
    .astrology()
    .get_daily_horoscope(&types::GetDailyHoroscopeParams::new(
        types::GetDailyHoroscopeParamsSign::Aries,
    ))
    .await?;
println!("{} {} {}", horoscope.overview, horoscope.love, horoscope.lucky_number);
# Ok(())
# }

Then expand into charts, compatibility, numerology, tarot, and more.

Quick start

use roxyapi::{Roxy, types};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Retries 429, 500, 502, 503 and 504 by default. Optional settings, shown with their defaults:
    // Roxy::builder(key).timeout(Duration::from_secs(30)).retry_policy(RetryPolicy::new(2)).build()?
    let roxy = Roxy::new(std::env::var("ROXY_API_KEY")?)?;
    let places = roxy
        .location()
        .search_cities(&types::SearchCitiesParams::new(
            "London, United Kingdom".into(),
        ))
        .await?;
    let city = places.cities.first().ok_or("No matching city")?;
    let birth = types::NatalChartRequest::new(
        "1990-01-15".into(),
        "14:30:00".into(),
        city.latitude,
        city.longitude,
        types::NatalChartRequestTimezone::String(city.timezone.clone()),
    );
    let chart = roxy
        .astrology()
        .generate_natal_chart(&Default::default(), &birth)
        .await?;
    println!("Ascendant: {}", chart.ascendant.sign);
    Ok(())
}

Domains

Domain	Accessor	Operations
Western Astrology	astrology()	39
Vedic Astrology	vedic_astrology()	58
Forecast	forecast()	5
Human Design	human_design()	12
Chinese Astrology	chinese_astrology()	16
Feng Shui	feng_shui()	11
Mesoamerican Astrology	mesoamerican_astrology()	18
Vastu	vastu()	10
Numerology	numerology()	20
Kabbalah	kabbalah()	12
Tarot	tarot()	10
Biorhythm	biorhythm()	6
Ayurveda	ayurveda()	8
I-Ching	iching()	9
Crystals and Healing Stones	crystals()	12
Dreams	dreams()	5
Angel Numbers	angel_numbers()	4
Location and Timezone	location()	3
Usage	usage()	1
Reports	reports()	9
Languages	languages()	2

Most-used endpoints

Start with one location lookup per person, then reuse the birth data across domains. These common calls cover charts, forecasts, readings and reference data. Each function returns errors to its caller with ?.

Location and Timezone

One location lookup feeds every chart. Select the intended city, then reuse its coordinates and IANA timezone.

# use roxyapi::{Roxy, types};
# use std::error::Error;
struct Birth {
    date: String,
    time: String,
    place: types::SearchCitiesResponseCitiesItem,
}

async fn location(roxy: &Roxy) -> Result<Birth, Box<dyn Error>> {
    let places = roxy
        .location()
        .search_cities(&types::SearchCitiesParams::new(
            "London, United Kingdom".into(),
        ))
        .await?;
    let place = places.cities.into_iter().next().ok_or("No matching city")?;
    println!("Birthplace: {}, {}", place.city, place.country);
    Ok(Birth {
        date: "1990-01-15".into(),
        time: "14:30:00".into(),
        place,
    })
}

Western Astrology

Natal charts, daily horoscopes and Moon phases. Build birth-chart products, daily content and lunar wellness features.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn astrology(roxy: &Roxy, birth: &Birth) -> Result<(), Box<dyn Error>> {
    let request = types::NatalChartRequest::new(
        birth.date.clone(),
        birth.time.clone(),
        birth.place.latitude,
        birth.place.longitude,
        types::NatalChartRequestTimezone::String(birth.place.timezone.clone()),
    );
    let natal = roxy
        .astrology()
        .generate_natal_chart(&Default::default(), &request)
        .await?;
    println!("Ascendant: {}", natal.ascendant.sign);
    let horoscope = roxy
        .astrology()
        .get_daily_horoscope(&types::GetDailyHoroscopeParams::new(
            types::GetDailyHoroscopeParamsSign::Aries,
        ))
        .await?;
    println!("Daily horoscope: {}", horoscope.overview);
    let moon = roxy
        .astrology()
        .get_current_moon_phase(&Default::default())
        .await?;
    println!("Moon: {}, illumination {}", moon.phase, moon.illumination);
    Ok(())
}

Vedic Astrology

Kundli, panchang, dasha, Mangal Dosha and KP ruling planets. Reuse the same birth and location for sidereal charts and timing tools.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn vedic_astrology(roxy: &Roxy, birth: &Birth, date: &str) -> Result<(), Box<dyn Error>> {
    let request = types::BirthChartRequest::new(
        birth.date.clone(),
        birth.time.clone(),
        birth.place.latitude,
        birth.place.longitude,
    )
    .with_timezone(types::BirthChartRequestTimezone::String(
        birth.place.timezone.clone(),
    ));
    let kundli = roxy
        .vedic_astrology()
        .generate_birth_chart(&Default::default(), &request)
        .await?;
    println!("Kundli houses: {}", kundli.houses.len());
    let request = types::GetDetailedPanchangRequest::new(
        date.into(),
        birth.place.latitude,
        birth.place.longitude,
    )
    .with_timezone(types::GetDetailedPanchangRequestTimezone::String(
        birth.place.timezone.clone(),
    ));
    let panchang = roxy
        .vedic_astrology()
        .get_detailed_panchang(&Default::default(), &request)
        .await?;
    println!("Tithi: {}", panchang.tithi.name);
    let request = types::GetCurrentDashaRequest::new(
        birth.date.clone(),
        birth.time.clone(),
        birth.place.latitude,
        birth.place.longitude,
    )
    .with_timezone(types::GetCurrentDashaRequestTimezone::String(
        birth.place.timezone.clone(),
    ));
    let dasha = roxy
        .vedic_astrology()
        .get_current_dasha(&Default::default(), &request)
        .await?;
    println!("Mahadasha: {}", dasha.mahadasha.planet);
    let request = types::ManglikRequest::new(
        birth.date.clone(),
        birth.time.clone(),
        birth.place.latitude,
        birth.place.longitude,
    )
    .with_timezone(types::ManglikRequestTimezone::String(
        birth.place.timezone.clone(),
    ));
    let dosha = roxy
        .vedic_astrology()
        .check_manglik_dosha(&Default::default(), &request)
        .await?;
    println!("Mangal Dosha present: {}", dosha.present);
    let request =
        types::GetKpRulingPlanetsRequest::new(birth.place.latitude, birth.place.longitude)
            .with_timezone(types::GetKpRulingPlanetsRequestTimezone::String(
                birth.place.timezone.clone(),
            ));
    let ruling = roxy
        .vedic_astrology()
        .get_kp_ruling_planets(&Default::default(), &request)
        .await?;
    println!("KP day lord: {}", ruling.day_lord);
    Ok(())
}

Forecast

Transit forecasts and a cross-domain timeline. Build dated event feeds with significance scores and descriptions.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn forecast(
    roxy: &Roxy,
    birth: &Birth,
    start_date: &str,
    end_date: &str,
) -> Result<(), Box<dyn Error>> {
    let subject = types::ForecastTransitsRequestBirthData::new(
        birth.date.clone(),
        birth.time.clone(),
        types::ForecastTransitsRequestBirthDataTimezone::String(birth.place.timezone.clone()),
    )
    .with_latitude(birth.place.latitude)
    .with_longitude(birth.place.longitude);
    let request = types::ForecastTransitsRequest::new(subject)
        .with_start_date(start_date.into())
        .with_end_date(end_date.into());
    let transits = roxy
        .forecast()
        .forecast_transits(&Default::default(), &request)
        .await?;
    for event in &transits.events {
        println!(
            "{}: {} ({})",
            event.date, event.description, event.significance
        );
    }
    let subject = types::GenerateTimelineRequestBirthData::new(
        birth.date.clone(),
        birth.time.clone(),
        types::GenerateTimelineRequestBirthDataTimezone::String(birth.place.timezone.clone()),
    )
    .with_latitude(birth.place.latitude)
    .with_longitude(birth.place.longitude);
    let request = types::GenerateTimelineRequest::new(subject)
        .with_start_date(start_date.into())
        .with_end_date(end_date.into());
    let timeline = roxy
        .forecast()
        .generate_timeline(&Default::default(), &request)
        .await?;
    for event in &timeline.events {
        println!("{} [{}]: {}", event.date, event.domain, event.description);
    }
    Ok(())
}

Human Design

A complete Human Design bodygraph. Read type, strategy, authority and profile for coaching and self-discovery.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn human_design(roxy: &Roxy, birth: &Birth) -> Result<(), Box<dyn Error>> {
    let request = types::GenerateBodygraphRequest::new(
        birth.date.clone(),
        birth.time.clone(),
        types::GenerateBodygraphRequestTimezone::String(birth.place.timezone.clone()),
    );
    let chart = roxy
        .human_design()
        .generate_bodygraph(&Default::default(), &request)
        .await?;
    println!(
        "{}: {}, {}, {}",
        chart.r#type, chart.strategy, chart.authority, chart.profile
    );
    Ok(())
}

Chinese Astrology

BaZi Four Pillars, zodiac animals and the daily almanac. Add birth readings and date-selection content with declared conventions.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn chinese_astrology(roxy: &Roxy, birth: &Birth, date: &str) -> Result<(), Box<dyn Error>> {
    let request = types::GenerateBaziChartRequest::new(
        birth.date.clone(),
        birth.time.clone(),
        types::GenerateBaziChartRequestTimezone::String(birth.place.timezone.clone()),
    );
    let bazi = roxy
        .chinese_astrology()
        .generate_bazi_chart(&Default::default(), &request)
        .await?;
    println!("Day Master: {}", bazi.day_master.element);
    let request = types::CalculateZodiacAnimalRequest::new(birth.date.clone());
    let animal = roxy
        .chinese_astrology()
        .calculate_zodiac_animal(&Default::default(), &request)
        .await?;
    println!("Chinese zodiac: {}", animal.animal.name);
    let day = roxy
        .chinese_astrology()
        .get_almanac_day(&types::GetAlmanacDayParams::new(date.into()))
        .await?;
    println!("Favourable activities: {:?}", day.favours);
    Ok(())
}

Feng Shui

Kua numbers and flying star charts. Read personal directions and the star arrangement of a property.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn feng_shui(roxy: &Roxy, birth: &Birth) -> Result<(), Box<dyn Error>> {
    let request = types::CalculateKuaNumberRequest::new(
        birth.date.clone(),
        types::CalculateKuaNumberRequestGender::Female,
    );
    let kua = roxy
        .feng_shui()
        .calculate_kua_number(&Default::default(), &request)
        .await?;
    println!("Kua: {}, group {}", kua.kua, kua.group);
    let stars = roxy
        .feng_shui()
        .generate_flying_star_chart(
            &Default::default(),
            &types::GenerateFlyingStarChartRequest::new()
                .with_period(9)
                .with_facing(types::GenerateFlyingStarChartRequestFacing::S2),
        )
        .await?;
    println!(
        "Facing: {}, structure {}",
        stars.facing.label, stars.structure.name
    );
    Ok(())
}

Mesoamerican Astrology

Tzolkin day signs and a full Maya chart. Add date-based readings with the calendar convention included in the response.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn mesoamerican_astrology(roxy: &Roxy, birth: &Birth) -> Result<(), Box<dyn Error>> {
    let request = types::CalculateTzolkinRequest::new(birth.date.clone());
    let tzolkin = roxy
        .mesoamerican_astrology()
        .calculate_tzolkin(&Default::default(), &request)
        .await?;
    println!("Tzolkin: {} {}", tzolkin.number, tzolkin.day_sign_name);
    let request = types::GenerateMayanChartRequest::new(birth.date.clone());
    let maya = roxy
        .mesoamerican_astrology()
        .generate_mayan_chart(&Default::default(), &request)
        .await?;
    println!("Calendar Round: {}", maya.calendar_round);
    Ok(())
}

Vastu

Vastu entrance analysis. Turn plot dimensions, facing and door position into a sourced entrance reading.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn vastu(roxy: &Roxy) -> Result<(), Box<dyn Error>> {
    let plot = types::CalculateEntrancePadaRequestPlot::new()
        .with_width(30.0)
        .with_depth(40.0)
        .with_unit(types::CalculateEntrancePadaRequestPlotUnit::Feet);
    let request = types::CalculateEntrancePadaRequest::new(plot)
        .with_facing(types::CalculateEntrancePadaRequestFacing::North)
        .with_door_position(0.4);
    let entrance = roxy
        .vastu()
        .calculate_entrance_pada(&Default::default(), &request)
        .await?;
    println!(
        "Entrance pada: {}, effect {}",
        entrance.pada, entrance.effect
    );
    Ok(())
}

Numerology

Life Path, a full numerology chart and Personal Year. Build name-and-birth-date readings without another location lookup.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn numerology(roxy: &Roxy, birth: &Birth) -> Result<(), Box<dyn Error>> {
    let mut date = birth.date.split('-');
    let year = date.next().ok_or("Missing birth year")?.parse()?;
    let month = date.next().ok_or("Missing birth month")?.parse()?;
    let day = date.next().ok_or("Missing birth day")?.parse()?;
    let life_path = roxy
        .numerology()
        .calculate_life_path(
            &Default::default(),
            &types::CalculateLifePathRequest::new(year, month, day),
        )
        .await?;
    println!("Life Path: {}", life_path.number);
    let request = types::GenerateNumerologyChartRequest::new("Jane Smith".into(), year, month, day);
    let chart = roxy
        .numerology()
        .generate_numerology_chart(&Default::default(), &request)
        .await?;
    println!("Core numbers: {:?}", chart.core_numbers);
    let request = types::CalculatePersonalYearRequest::new(month, day);
    let personal_year = roxy
        .numerology()
        .calculate_personal_year(&Default::default(), &request)
        .await?;
    println!(
        "Personal Year: {}, {}",
        personal_year.personal_year, personal_year.theme
    );
    Ok(())
}

Kabbalah

Gematria and the Hebrew birth profile. Explore a name and the Hebrew birthday, angels and sephirah for a birth instant.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn kabbalah(roxy: &Roxy, birth: &Birth) -> Result<(), Box<dyn Error>> {
    let gematria = roxy
        .kabbalah()
        .calculate_gematria(
            &Default::default(),
            &types::CalculateGematriaRequest::new().with_text("Sarah".into()),
        )
        .await?;
    println!("Hebrew form: {}", gematria.chosen.hebrew);
    for cipher in &gematria.values {
        println!("{}: {}", cipher.name, cipher.value);
    }
    let request = types::GenerateBirthProfileRequest::new(
        birth.date.clone(),
        types::GenerateBirthProfileRequestTimezone::String(birth.place.timezone.clone()),
    )
    .with_time(birth.time.clone());
    let profile = roxy
        .kabbalah()
        .generate_birth_profile(&Default::default(), &request)
        .await?;
    println!("Hebrew birthday: {}", profile.hebrew_date.hebrew);
    Ok(())
}

Tarot

Daily tarot cards, three-card spreads, Celtic Cross and yes-or-no readings. Reuse a seed for reproducible readings in journaling and reflection apps.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn tarot(roxy: &Roxy) -> Result<(), Box<dyn Error>> {
    let seed = "reading-example";
    let daily = roxy
        .tarot()
        .get_daily_card(
            &Default::default(),
            &types::GetDailyCardRequest::new().with_seed(seed.into()),
        )
        .await?;
    println!("Daily card: {}, {}", daily.card.name, daily.daily_message);
    let three = roxy
        .tarot()
        .cast_three_card(
            &Default::default(),
            &types::CastThreeCardRequest::new()
                .with_question("What should I focus on next quarter?".into())
                .with_seed(seed.into()),
        )
        .await?;
    for position in &three.positions {
        println!("{}: {}", position.name, position.card.name);
    }
    let celtic = roxy
        .tarot()
        .cast_celtic_cross(
            &Default::default(),
            &types::CastCelticCrossRequest::new()
                .with_question("What should I understand about this situation?".into())
                .with_seed(seed.into()),
        )
        .await?;
    for position in &celtic.positions {
        println!("{}: {}", position.name, position.interpretation);
    }
    let answer = roxy
        .tarot()
        .cast_yes_no(
            &Default::default(),
            &types::CastYesNoRequest::new()
                .with_question("Should I take this opportunity?".into())
                .with_seed(seed.into()),
        )
        .await?;
    println!("Answer: {}, strength {}", answer.answer, answer.strength);
    Ok(())
}

Biorhythm

Biorhythm readings and forecasts. Add cycle and energy summaries to entertainment and reflection features.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,
# }
async fn biorhythm(
    roxy: &Roxy,
    birth: &Birth,
    start_date: &str,
    end_date: &str,
) -> Result<(), Box<dyn Error>> {
    let request =
        types::GetReadingRequest::new(birth.date.clone()).with_target_date(start_date.into());
    let reading = roxy
        .biorhythm()
        .get_reading(&Default::default(), &request)
        .await?;
    println!("Energy: {}", reading.energy_rating);
    if let Some(physical) = reading.cycles.additional_properties.get("physical") {
        println!("Physical cycle: {}", physical.value);
    }
    let request = types::GetForecastRequest::new(birth.date.clone())
        .with_start_date(start_date.into())
        .with_end_date(end_date.into());
    let forecast = roxy
        .biorhythm()
        .get_forecast(&Default::default(), &request)
        .await?;
    println!(
        "Best day: {}, average energy {}",
        forecast.summary.best_day, forecast.summary.average_energy
    );
    Ok(())
}

Ayurveda

Dosha constitution and the local daily routine. Read the birth-chart profile and sunrise-based routine with their explanatory notes.

# use roxyapi::{Roxy, types};
# use std::error::Error;
# struct Birth {
#     date: String,
#     time: String,
#     place: types::SearchCitiesResponseCitiesItem,