RoxyAPI MCP sunucusu

RoxyAPI Go SDK

The official Go SDK for RoxyAPI, the typed astrology API for Go: 18+ insight domains and 258+ endpoints behind one API key, with ephemeris output verified against NASA JPL Horizons across 210 reference points. Western and Vedic astrology, forecast, human design, Chinese astrology, feng shui, Mesoamerican astrology, Vastu, numerology, Kabbalah, tarot, biorhythm, Ayurveda, I Ching, crystals, dreams, angel numbers, and location geocoding, all from one go get. Build anything, fast.

A fully typed, idiomatic golang client generated from the live OpenAPI spec: one direct runtime dependency, the standard library net/http underneath, autocomplete on every endpoint and field, and bundled docs for AI coding agents.

• One key, every domain. Eighteen plus insight domains under a single subscription, with flat all-inclusive pricing.
• Typed end to end. Domain grouped methods, typed request bodies, typed responses, and one catchable error type. Your editor walks the whole API.
• Lean. Standard net/http and one direct dependency. No vendor cloud, no heavy framework.
• Agent ready. Bundled AGENTS.md and docs/llms-full.txt, plus a remote MCP server per domain.
• Proof before pay. The playground at https://roxyapi.com/api-reference returns real production responses.

Build horoscope apps and daily push readings, natal and Vedic birth chart generators, compatibility and synastry matchers, numerology and tarot experiences, human design bodygraphs, transit and forecast timelines, biorhythm trackers, dream and angel number lookups, and AI agents that reason over any of it through MCP.

Install

go get github.com/RoxyAPI/sdk-go

Start with one call

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

roxy, err := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
if err != nil {
	panic(err)
}
horoscope, err := roxy.Astrology.GetDailyHoroscope(context.Background(), "aries", nil)
if err != nil {
	panic(err) // a 4xx or 5xx is returned as *roxyapi.RoxyError
}
fmt.Println(horoscope.JSON200.Overview, horoscope.JSON200.Love, horoscope.JSON200.LuckyNumber)

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

Quick start

Two small helpers do the fiddly work: roxyapi.Date(y, m, d) builds a date field, and roxyapi.Ptr(v) sets any optional pointer field.

package main

import (
	"context"
	"fmt"
	"os"
	"time"

	roxyapi "github.com/RoxyAPI/sdk-go"
)

func main() {
	// Retries 429, 500, 502, 503 and 504 by default. Optional settings, shown with their defaults:
	// roxyapi.NewRoxy(key, roxyapi.WithRetry(roxyapi.RetryConfig{MaxRetries: 2, InitialDelay: 500 * time.Millisecond, MaxDelay: 30 * time.Second}))
	roxy, err := roxyapi.NewRoxy(os.Getenv("ROXY_API_KEY"))
	if err != nil {
		panic(err)
	}
	ctx := context.Background()

	// Step 1: geocode the birth city once. Every chart endpoint takes these three values.
	search, err := roxy.Location.SearchCities(ctx, &roxyapi.SearchCitiesParams{Q: "London"})
	if err != nil {
		panic(err)
	}
	if len(search.JSON200.Cities) == 0 {
		panic("no city matched the search") // a 200 can still return zero cities
	}
	city := search.JSON200.Cities[0] // City, Country, Latitude, Longitude, Timezone (IANA), UtcOffset

	// Step 2: a Western natal chart. Timezone is a per-request union; pass the IANA string
	// from the lookup ("Europe/London") and the server resolves it to the DST-correct
	// offset for the date of the chart.
	var tz roxyapi.NatalChartRequest_Timezone
	if err := tz.FromNatalChartRequestTimezone1(city.Timezone); err != nil {
		panic(err)
	}
	chart, err := roxy.Astrology.GenerateNatalChart(ctx, nil, roxyapi.NatalChartRequest{
		Date:     roxyapi.Date(1990, time.January, 15),
		Time:     "14:30:00",
		Latitude: city.Latitude, Longitude: city.Longitude, Timezone: tz,
	})
	if err != nil {
		panic(err)
	}

	// Step 3: the same birth as a Vedic kundli. Same inputs, sidereal zodiac. Vedic bodies
	// take Timezone as an optional pointer (omit it to default to IST).
	var vtz roxyapi.BirthChartRequest_Timezone
	if err := vtz.FromBirthChartRequestTimezone1(city.Timezone); err != nil {
		panic(err)
	}
	kundli, err := roxy.VedicAstrology.GenerateBirthChart(ctx, nil, roxyapi.BirthChartRequest{
		Date:     roxyapi.Date(1990, time.January, 15),
		Time:     "14:30:00",
		Latitude: city.Latitude, Longitude: city.Longitude, Timezone: &vtz,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(chart.JSON200.Ascendant.Sign, kundli.JSON200.Meta["Moon"].Rashi)
}

NewRoxy sets the base URL (https://roxyapi.com/api/v2) and injects the auth header and SDK identification header on every request. Every method returns (resp, err): check err first, then read the typed body off resp.JSON200 (see Error handling).

Domains

Reach every domain through its accessor on the client returned by NewRoxy.

Accessor	What it covers
roxy.Astrology	Western astrology API for natal birth charts, daily, weekly, monthly, and yearly horoscopes with unique content per s...
roxy.VedicAstrology	Vedic astrology (Jyotish) and KP API for kundli generation with the sixteen Shodasavarga divisional charts (D1 to D60...
roxy.Forecast	Astrology forecast API that merges upcoming transit aspects, sign ingresses, retrograde stations, new and full moons,...
roxy.HumanDesign	Human Design API that generates the full bodygraph from a birth moment: type, strategy, inner authority, profile, def...
roxy.ChineseAstrology	Chinese zodiac and BaZi astrology API: Four Pillars charts, Chinese zodiac signs and the Chinese lunisolar calendar f...
roxy.FengShui	Compute classical feng shui from one API: Xuan Kong flying star natal charts for any of the nine periods and 24 mount...
roxy.MesoamericanAstrology	Calculate Mayan astrology day signs, the Tzolkin sacred round, the Haab year, the full Long Count and the Aztec tonal...
roxy.Vastu	Vastu Shastra API for directional home and plot analysis: entrance padas with the classical effect of each of the 32...
roxy.Numerology	Numerology API for life path numbers, complete numerology charts and compatibility, in both Pythagorean and Chaldean...
roxy.Kabbalah	Kabbalah API for gematria, the 72 names, the Tree of Life and the Hebrew birthday
roxy.Tarot	Tarot reading API with the complete 78-card Rider-Waite-Smith deck and card meanings for love, career, health, and sp...
roxy.Biorhythm	Biorhythm API for entertainment and reflection, with 10 model cycle types across 3 primary (physical, emotional, inte...
roxy.Ayurveda	Ayurveda API for dosha profiles, the dinacharya daily routine and the ritucharya seasonal regimen, with a verse cited...
roxy.Iching	I-Ching oracle API with all 64 hexagrams, 384 changing lines, 8 trigrams, and modern interpretations for love, career...
roxy.Crystals	Crystal healing API covering the most popular and widely-searched healing crystals and gemstones, from Amethyst and R...
roxy.Dreams	Dream interpretation API with a 2,200+ symbol dream dictionary and psychological meanings covering animals, objects,...
roxy.AngelNumbers	Angel numbers API with meanings for 111, 222, 333, 444, 555, 666, 777, 888, 999, 1111, and 75+ sequences covering eve...
roxy.Location	Timezone and location API with city search and geocoding across 5,180,000+ cities, towns and villages in 240+ countri...
roxy.Usage	Monitor your API usage, check rate limits, and track request consumption
roxy.Reports	Branded reports built from the API: a natal chart and more as a print-ready PDF, self-contained HTML or Markdown, whi...
roxy.Languages	List the response languages accepted by the lang query parameter on every i18n-aware endpoint

Most-used endpoints

The highest-demand endpoints by domain, in the order you are most likely to ship them. Every example below reads the same birth through a different domain, and every coordinate comes from one location lookup at the top: one API key, one lookup, and eighteen domains that compose into a single product instead of eighteen separate ones. Full catalog in the API reference; method index in docs/llms-full.txt.

The blocks are written inside a function that returns error, so every call is followed by its if err != nil check. Each response is read off JSON200; the comment under a call names the fields as they sit there, and an optional field is a pointer (nil when absent). Each chart body carries its own Timezone union type, built from the IANA string with the generated From...Timezone1 method as in the Quick start; bodies whose nested person or plot structs have no named type are filled field by field.

Location first: one lookup feeds every chart

Every chart, horoscope, panchang, dasha, dosha, synastry and compatibility endpoint needs Latitude, Longitude and Timezone. Never ask users to type coordinates. Look the city up once and reuse the result in every domain below.

// One lookup feeds every chart below. Timezone is the IANA name from the city
// record; the server resolves it to the DST-correct offset for the date of each chart.
place, err := roxy.Location.SearchCities(ctx, &roxyapi.SearchCitiesParams{Q: "New York"})
if err != nil {
	return err
}
city := place.JSON200.Cities[0]
latitude, longitude, timezone := city.Latitude, city.Longitude, city.Timezone
birthDate, birthTime := roxyapi.Date(1990, time.January, 15), "14:30:00"

// A second person for the two-chart calls (synastry, Guna Milan, Human Design connection).
london, err := roxy.Location.SearchCities(ctx, &roxyapi.SearchCitiesParams{Q: "London"})
if err != nil {
	return err
}
partner := london.JSON200.Cities[0] // Latitude, Longitude and Timezone for the second chart
partnerDate, partnerTime := roxyapi.Date(1992, time.July, 22), "09:00:00"

1. Western astrology API (natal chart, daily horoscope, synastry)

Natal chart products, daily horoscope features, dating and compatibility apps, and lunar-cycle wellness apps start here.

// Natal chart. The most requested Western call, run once at onboarding.
// The body carries the latitude, longitude and timezone from the location lookup above.
var natalTz roxyapi.NatalChartRequest_Timezone
if err := natalTz.FromNatalChartRequestTimezone1(timezone); err != nil {
	return err
}
natal, err := roxy.Astrology.GenerateNatalChart(ctx, nil, roxyapi.NatalChartRequest{
	Date: birthDate, Time: birthTime, Latitude: latitude, Longitude: longitude, Timezone: natalTz,
})
if err != nil {
	return err
}
// natal.JSON200.Planets[n].Name, .Sign, .House, .Interpretation.Summary; natal.JSON200.Ascendant.Sign; natal.JSON200.Aspects

// Daily horoscope. The highest per-user call frequency in the catalog: daily content, streaks, push.
horoscope, err := roxy.Astrology.GetDailyHoroscope(ctx, "aries", nil)
if err != nil {
	return err
}
// horoscope.JSON200.Overview, .Love, .Career, .Column, .Events, .LuckyNumber

// Synastry. Full inter-aspect analysis between two charts, the relationship feature of dating apps.
// Person1 and Person2 are inline structs, so the body is filled field by field from the two lookups above.
var synastryBody roxyapi.CalculateSynastryJSONRequestBody
synastryBody.Person1.Date, synastryBody.Person1.Time = birthDate, birthTime
synastryBody.Person1.Latitude, synastryBody.Person1.Longitude = latitude, longitude
if err := synastryBody.Person1.Timezone.FromCalculateSynastryJSONBodyPerson1Timezone1(timezone); err != nil {
	return err
}
synastryBody.Person2.Date, synastryBody.Person2.Time = partnerDate, partnerTime
synastryBody.Person2.Latitude, synastryBody.Person2.Longitude = partner.Latitude, partner.Longitude
if err := synastryBody.Person2.Timezone.FromCalculateSynastryJSONBodyPerson2Timezone1(partner.Timezone); err != nil {
	return err
}
synastry, err := roxy.Astrology.CalculateSynastry(ctx, nil, synastryBody)
if err != nil {
	return err
}
// synastry.JSON200.CompatibilityScore, .InterAspects, .Analysis.Strengths

// Moon phase. A zero-setup GET for wellness, cycle-tracking and meditation apps.
moon, err := roxy.Astrology.GetCurrentMoonPhase(ctx, nil)
if err != nil {
	return err
}
// moon.JSON200.Phase, .Illumination, .Sign, .Meaning.Description

2. Vedic astrology API (kundli, panchang, dasha, Guna Milan, KP)

Kundli generators, matrimonial matching, muhurta and panchang apps, and KP practitioners. The same birth values, read sidereally.

// Vedic kundli. The same birth read sidereally: the body reuses the location lookup above.
// Vedic bodies take Timezone as an optional pointer; omit it to default to IST.
var kundliTz roxyapi.BirthChartRequest_Timezone
if err := kundliTz.FromBirthChartRequestTimezone1(timezone); err != nil {
	return err
}
kundli, err := roxy.VedicAstrology.GenerateBirthChart(ctx, nil, roxyapi.BirthChartRequest{
	Date: birthDate, Time: birthTime, Latitude: latitude, Longitude: longitude, Timezone: &kundliTz,
})
if err != nil {
	return err
}
// kundli.JSON200.Meta["Moon"].Rashi, kundli.JSON200.Meta["Moon"].Nakshatra.Name, kundli.JSON200.Houses, .Combustion

// Detailed panchang. Tithi, nakshatra, yoga, karana, rahu kaal and the muhurtas for a date and place.
var panchangTz roxyapi.GetDetailedPanchangJSONBody_Timezone
if err := panchangTz.FromGetDetailedPanchangJSONBodyTimezone1(timezone); err != nil {
	return err
}
panchang, err := roxy.VedicAstrology.GetDetailedPanchang(ctx, nil, roxyapi.GetDetailedPanchangJSONRequestBody{
	Date: roxyapi.Date(2026, time.October, 1), Latitude: latitude, Longitude: longitude, Timezone: &panchangTz,
})
if err != nil {
	return err
}
// panchang.JSON200.Tithi, .Nakshatra, .RahuKaal, .AbhijitMuhurta

// Vimshottari dasha. The mahadasha, antardasha and pratyantardasha running right now.
var dashaTz roxyapi.GetCurrentDashaJSONBody_Timezone
if err := dashaTz.FromGetCurrentDashaJSONBodyTimezone1(timezone); err != nil {
	return err
}
dasha, err := roxy.VedicAstrology.GetCurrentDasha(ctx, nil, roxyapi.GetCurrentDashaJSONRequestBody{
	Date: birthDate, Time: birthTime, Latitude: latitude, Longitude: longitude, Timezone: &dashaTz,
})
if err != nil {
	return err
}
// dasha.JSON200.Mahadasha, .Antardasha, .RemainingInMahadasha

// Mangal Dosha. The most asked matrimonial check.
var doshaTz roxyapi.ManglikRequest_Timezone
if err := doshaTz.FromManglikRequestTimezone1(timezone); err != nil {
	return err
}
dosha, err := roxy.VedicAstrology.CheckManglikDosha(ctx, nil, roxyapi.ManglikRequest{
	Date: birthDate, Time: birthTime, Latitude: latitude, Longitude: longitude, Timezone: &doshaTz,
})
if err != nil {
	return err
}
// dosha.JSON200.Present; Severity and Remedies are pointers, set only when Present is true

// Guna Milan. The 36-point Ashtakoota score behind kundli matching, both people from the lookups above.
var milanBody roxyapi.CompatibilityRequest
milanBody.Person1.Date, milanBody.Person1.Time = birthDate, birthTime
milanBody.Person1.Latitude, milanBody.Person1.Longitude = latitude, longitude
milanBody.Person1.Timezone = new(roxyapi.CompatibilityRequest_Person1_Timezone)
if err := milanBody.Person1.Timezone.FromCompatibilityRequestPerson1Timezone1(timezone); err != nil {
	return err
}
milanBody.Person2.Date, milanBody.Person2.Time = partnerDate, partnerTime
milanBody.Person2.Latitude, milanBody.Person2.Longitude = partner.Latitude, partner.Longitude
milanBody.Person2.Timezone = new(roxyapi.CompatibilityRequest_Person2_Timezone)
if err := milanBody.Person2.Timezone.FromCompatibilityRequestPerson2Timezone1(partner.Timezone); err != nil {
	return err
}
milan, err := roxy.VedicAstrology.CalculateGunMilan(ctx, nil, milanBody)
if err != nil {
	return err
}
// milan.JSON200.Total, .Percentage, .IsCompatible, .Breakdown

// KP ruling planets. Horary answers at the moment of the question, for the place looked up above.
var kpTz roxyapi.GetKpRulingPlanetsJSONBody_Timezone
if err := kpTz.FromGetKpRulingPlanetsJSONBodyTimezone1(timezone); err != nil {
	return err
}
kp, err := roxy.VedicAstrology.GetKpRulingPlanets(ctx, nil, roxyapi.GetKpRulingPlanetsJSONRequestBody{
	Latitude: latitude, Longitude: longitude, Timezone: &kpTz,
})
if err != nil {
	return err
}
// kp.JSON200.DayLord, .MoonSublord, .RulingPlanets

3. Astrology forecast API (transit forecast, cross-domain timeline)

Forecast feeds, transit alerts and timing tools. One call returns a dated, significance-scored event list; the timeline variant merges Vedic dasha boundaries and biorhythm critical days into the same list, which no single-domain API can do.

// Transit forecast. Transit-to-natal aspects, sign ingresses and retrograde stations over a window.
// BirthData is an inline struct carrying the same birth: date, time, latitude, longitude, timezone.
var transitsBody roxyapi.ForecastTransitsJSONRequestBody
transitsBody.BirthData.Date, transitsBody.BirthData.Time = birthDate, birthTime
transitsBody.BirthData.Latitude, transitsBody.BirthData.Longitude = roxyapi.Ptr(latitude), roxyapi.Ptr(longitude)
if err := transitsBody.BirthData.Timezone.FromForecastTransitsJSONBodyBirthDataTimezone1(timezone); err != nil {
	return err
}
transitsBody.StartDate, transitsBody.EndDate = roxyapi.Ptr(roxyapi.Date(2026, time.October, 1)), roxyapi.Ptr(roxyapi.Date(2026, time.October, 31))
transits, err := roxy.Forecast.ForecastTransits(ctx, nil, transitsBody)
if err != nil {
	return err
}
// transits.JSON200.Count, transits.JSON200.Events[n].Date, .Type, .Body, .Target, .Aspect, .Significance

// Cross-domain timeline. The same window with Vedic dasha boundaries and biorhythm critical days merged in.
var timelineBody roxyapi.GenerateTimelineJSONRequestBody
timelineBody.BirthData.Date, timelineBody.BirthData.Time = birthDate, birthTime
timelineBody.BirthData.Latitude, timelineBody.BirthData.Longitude = roxyapi.Ptr(latitude), roxyapi.Ptr(longitude)
if err := timelineBody.BirthData.Timezone.FromGenerateTimelineJSONBodyBirthDataTimezone1(timezone); err != nil {
	return err
}
timelineBody.StartDate, timelineBody.EndDate = roxyapi.Ptr(roxyapi.Date(2026, time.October, 1)), roxyapi.Ptr(roxyapi.Date(2026, time.October, 31))
timeline, err := roxy.Forecast.GenerateTimeline(ctx, nil, timelineBody)
if err != nil {
	return err
}
// timeline.JSON200.Events[n].Domain ("western", "vedic" or "biorhythm"), .Description, .Significance

4. Human Design API (bodygraph, connection)

Self-discovery apps, coaching bots and compatibility products. The full bodygraph is one call, and the Design side is solved on the exact 88-degree solar arc rather than approximated as calendar days.

// Bodygraph. Type, strategy, authority, profile, definition, centers, channels and all 26 gates in one call.
// Human Design needs only the birth instant, so it takes the date, time and timezone from the lookup above.
var hdTz roxyapi.GenerateBodygraphJSONBody_Timezone
if err := hdTz.FromGenerateBodygraphJSONBodyTimezone1(timezone); err != nil {
	return err
}
hd, err := roxy.HumanDesign.GenerateBodygraph(ctx, nil, roxyapi.GenerateBodygraphJSONRequestBody{
	Date: birthDate, Time: birthTime, Timezone: hdTz,
})
if err != nil {
	return err
}
// hd.JSON200.Type, .Strategy, .Authority, .Profile, .Definition, .IncarnationCross.Name, .Centers, .Channels, .Gates

// Connection. Two bodygraphs combined, each of the 36 channels classified by how the pair forms it.
var connectionBody roxyapi.CalculateConnectionJSONRequestBody
connectionBody.PersonA.Date, connectionBody.PersonA.Time = birthDate, birthTime
if err := connectionBody.PersonA.Timezone.FromCalculateConnectionJSONBodyPersonATimezone1(timezone); err != nil {
	return err
}
connectionBody.PersonB.Date, connectionBody.PersonB.Time = partnerDate, partnerTime
if err := connectionBody.PersonB.Timezone.FromCalculateConnectionJSONBodyPersonBTimezone1(partner.Timezone); err != nil {
	return err
}
connection, err := roxy.HumanDesign.CalculateConnection(ctx, nil, connectionBody)
if err != nil {
	return err
}
// connection.JSON200.TotalChannels, .Summary.Electromagnetic, .CombinedDefinition