Skip to content
RoxyAPI
Get API Key
Set up your AI agentGet startedAPI ReferenceSDKRemote MCPFree Templates

Astrology SDKs for your app

Official RoxyAPI SDKs for TypeScript, Python, PHP, C#, Go, and Rust give your app methods for natal charts, compatibility readings, forecasts and the rest of the catalog, all based on the published OpenAPI request contract. Use this guide to resolve a birthplace, call a chart endpoint and handle its response in your server code. The WordPress plugin adds Gutenberg blocks and shortcodes for sites built in a page editor.

TypeScript TypeScript npm
Python Python PyPI
PHP PHP Packagist
C# and .NET C# / .NET NuGet
Go Go pkg.go.dev
Rust Rust crates.io
WordPress WordPress wordpress.org

Install

bash
npm install @roxyapi/sdk

Quick start

Initialize the client once and reuse it across calls. Each SDK configures the API base URL and request credentials.

typescript
import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

// Daily horoscope
const { data } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'aries' },
});

// Numerology life path
const { data: lp } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 1, day: 15 },
});

// Tarot Celtic Cross spread
const { data: reading } = await roxy.tarot.castCelticCross({
  body: { question: 'What should I focus on this month?' },
});

Never expose your secret API key in client-side code. Call RoxyAPI from your server, API routes, serverless functions, or background workers only.

Authentication

Pass your API key on initialization. Get your API key, delivered instantly after checkout.

typescript
import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

Domains

Each domain is a namespace on the roxy instance.

Namespace (TS / PHP)Namespace (Python)What it covers
roxy.astrology / $roxy->astrologyroxy.astrologyWestern astrology: natal charts, horoscopes, synastry, transits, moon phases
roxy.vedicAstrology / $roxy->vedicAstrologyroxy.vedic_astrologyVedic / Jyotish: kundli, panchang, dashas, nakshatras, doshas, KP system
roxy.numerology / $roxy->numerologyroxy.numerologyLife path, expression, soul urge, personal year, karmic lessons
roxy.tarot / $roxy->tarotroxy.tarotDaily card, custom draws, three-card, Celtic Cross, yes / no, love spread
roxy.humanDesign / $roxy->humanDesignroxy.human_designHuman Design: bodygraph, type, authority, profile, centers, channels, gates, connection chart
roxy.forecast / $roxy->forecastroxy.forecastCross-domain forecast: transit timelines, significant dates, merged Western, Vedic, and biorhythm events
roxy.chineseAstrology / $roxy->chineseAstrologyroxy.chinese_astrologyChinese astrology: BaZi four pillars, Day Master strength, luck pillars, zodiac animals, lunisolar calendar, Tong Shu almanac
roxy.fengShui / $roxy->fengShuiroxy.feng_shuiFeng shui: Kua number, Eight Mansions directions, flying star charts, annual afflictions, bagua sectors, nine-period cycle
roxy.biorhythm / $roxy->biorhythmroxy.biorhythmDaily check-in, multi-day forecast, critical days, compatibility
roxy.iching / $roxy->ichingroxy.ichingDaily hexagram, three-coin cast, 64 hexagrams, trigrams
roxy.crystals / $roxy->crystalsroxy.crystalsCrystal meanings, zodiac / chakra pairings, birthstone, search
roxy.dreams / $roxy->dreamsroxy.dreamsDream symbol dictionary, interpretations
roxy.angelNumbers / $roxy->angelNumbersroxy.angel_numbersNumber meanings, universal digit-root lookup, daily
roxy.location / $roxy->locationroxy.locationCity search for birth chart coordinates
roxy.usage / $roxy->usageroxy.usageAPI usage stats, remaining quota, subscription info

Location first

Every chart, horoscope, panchang, dasha, dosha, navamsa, KP, synastry, compatibility, and natal endpoint needs latitude, longitude, and a timezone. Call the location API first, then feed the result into the chart method.

The location response is a pagination envelope. Each city has both an IANA timezone string and a decimal utcOffset. Pass the IANA string as timezone: chart endpoints resolve it to the offset in force on the birth date. utcOffset is the offset in effect today, so it is wrong for any birth on the other side of a daylight saving change.

typescript
const { data, error } = await roxy.location.searchCities({
  query: { q: 'London, UK' },
});
if (error) throw error;

// Response: { total, limit, offset, cities: [...] }
const { latitude, longitude, timezone } = data.cities[0];

const { data: chart } = await roxy.vedicAstrology.generateBirthChart({
  body: {
    date: '1990-01-15',
    time: '14:30:00',
    latitude,
    longitude,
    timezone, // IANA string like "Europe/London". Server resolves DST for the chart date
  },
});

Chart endpoints accept timezone as either a decimal number (-5 for EST, 1 for CET, 9 for Tokyo) or an IANA identifier ("America/New_York", "Europe/London"). IANA strings are resolved server-side to the DST-correct offset for the request date, so a January 1990 New York birth gets EST (-5) even when you geocoded the city in July. The utcOffset field on the Location response is a convenience decimal if you prefer numbers. Both forms produce identical charts.

Examples

Daily horoscope

typescript
const { data, error } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'scorpio' },
});

if (error) {
  console.error(error);
} else {
  console.log(data.overview); // General daily forecast
  console.log(data.love);     // Love and relationship forecast
  console.log(data.career);   // Career outlook
}

Numerology life path

typescript
const { data, error } = await roxy.numerology.calculateLifePath({
  body: { year: 1990, month: 1, day: 15 },
});
if (error) throw error;

console.log(data.number); // e.g. 7
console.log(data.type);   // "single" | "master"

Vedic birth chart

The response groups planets by the rashi (sign) they occupy. Each rashi has a signs[] array (planets in that rashi, often empty) plus a top-level meta dict with every planet keyed by name.

typescript
const { data, error } = await roxy.vedicAstrology.generateBirthChart({
  body: {
    date: '1990-01-15',
    time: '14:30:00',
    latitude: 40.7128,
    longitude: -74.006,
    timezone: -5,
  },
});
if (error) throw error;

// Iterate rashis (aries..pisces) for the 12-sign chart
for (const rashi of ['aries', 'taurus', 'gemini'] as const) {
  console.log(rashi, data[rashi].signs); // planets in this rashi
}

// Or look up any planet directly
console.log(data.meta.Sun.rashi);            // "Capricorn"
console.log(data.meta.Moon.nakshatra.name);  // nakshatra name

Western natal chart

typescript
const { data, error } = await roxy.astrology.generateNatalChart({
  body: {
    date: '1990-01-15',
    time: '14:30:00',
    latitude: 40.7128,
    longitude: -74.006,
    timezone: -5,
  },
});
if (error) throw error;

console.log(data.planets.length);  // planets, the lunar nodes and Chiron
console.log(data.houses.length);   // 12
console.log(data.ascendant.sign);  // ascendant zodiac sign
console.log(data.midheaven.sign);  // midheaven zodiac sign

Tarot daily card

typescript
const { data, error } = await roxy.tarot.getDailyCard({ body: { seed: 'user-123' } });
if (error) throw error;
console.log(data.card.name);    // e.g. "The Star"
console.log(data.dailyMessage); // concise daily guidance
console.log(data.card.meaning); // full card interpretation

Angel number lookup

typescript
const { data, error } = await roxy.angelNumbers.getAngelNumber({
  path: { number: '1111' },
});
if (error) throw error;
console.log(data.coreMessage);       // Short divine message summary
console.log(data.meaning.spiritual); // Spiritual interpretation
console.log(data.meaning.love);      // Love / relationship meaning

Check usage

typescript
const { data, error } = await roxy.usage.getUsageStats();
if (error) throw error;
console.log(`${data.usedThisMonth} / ${data.requestsPerMonth} requests used`);

Multi-language responses

Interpretations are available in ten languages: English (en), Turkish (tr), German (de), Spanish (es), French (fr), Hindi (hi), Portuguese (pt), Russian (ru), Chinese Simplified (zh-Hans), Chinese Traditional (zh-Hant).

typescript
const { data } = await roxy.tarot.getDailyCard({
  body: { date: '2026-04-22' },
  query: { lang: 'es' },
});

Supported: astrology, vedicAstrology / vedic_astrology, forecast, humanDesign / human_design, chineseAstrology / chinese_astrology, fengShui / feng_shui, mesoamericanAstrology / mesoamerican_astrology, vastu, numerology, kabbalah, tarot, biorhythm, ayurveda, iching, crystals, angelNumbers / angel_numbers. English-only: dreams, location, usage.

Async support

typescript
// Already async: every method returns a Promise
const { data } = await roxy.astrology.getDailyHoroscope({ path: { sign: 'aries' } });

Error handling

TypeScript returns { data, error, response } per call. Python raises RoxyAPIError. PHP throws RoxyApiException. C# throws RoxyError, or the base ApiException for a status the endpoint does not declare. Go returns (resp, error) where any 4xx/5xx is a *roxyapi.RoxyError. Rust returns Result<T, roxyapi::Error>; an HTTP failure is Error::Api with status, code, error and optional doc_url. Match the stable code when choosing what to do next: every SDK ships the codes as typed constants, so a typo fails to compile or lint instead of silently never matching.

All six SDKs already retry for you, so a catch block never needs a sleep and retry loop. By the time an error reaches your code the retries have run out, or the wait was one a retry should not sit through, such as an exhausted monthly allowance. Each error carries doc_url and the Retry-After wait, under the name each tab shows.

typescript
import { createRoxy, ErrorCodes, retryAfterSeconds } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data, error, response } = await roxy.tarot.castYesNo({
  body: { question: 'Should I take this opportunity?' },
});

if (error) {
  switch (error.code) {
    case ErrorCodes.ValidationError:
      console.error('Bad input:', error.error);
      break;
    case ErrorCodes.RateLimitExceeded:
      console.error('Monthly quota reached, resets in', retryAfterSeconds(response), 'seconds');
      break;
    default:
      console.error('API error:', error.code, error.error, error.doc_url);
  }
} else {
  console.log(data.answer); // "Yes" | "No" | "Maybe"
}

ErrorCodes holds every code as a typed constant, and retryAfterSeconds(response) returns the Retry-After wait in seconds, or undefined. Pass { maxRetries: 0 } as the second argument of createRoxy to turn retries off, or maxRetries, initialDelayMs and maxDelayMs to tune them.

Retries

TypeScript, Python, PHP, C#, Go and Rust retry twice by default, with jittered backoff, on 429, 500, 502, 503 and 504 and on a connection that never reached the API, and they honour Retry-After. A wait longer than 30 seconds, which is what an exhausted monthly allowance asks for, is not waited out: the error comes back at once with the wait attached. Setting the retry count to 0 turns retries off.

Retry 429 with code rate_limit_per_minute and 503 with code compute_saturated after the Retry-After seconds. Retry 500 with code internal_error with exponential backoff. A request that fails on our side with a 5xx does not count against your monthly allowance, so retrying it is free. A 429 with code rate_limit_exceeded means the monthly allowance is used up: retrying cannot help before the reset, and Retry-After gives the seconds to it. Fix the request for any other 4xx, because it will fail the same way until it changes. Every official SDK already retries these for you, twice and honouring Retry-After, so a call made through an SDK needs no second retry loop.

Error codes

Every code, the status it arrives with, and what to change for each one is on the error codes page. It is one entry per code, and every failed response carries a doc_url that links directly to its own entry, so an SDK error can be looked up without searching.

The code field is machine-readable and stable, safe to switch on. The error field is human-readable and may change wording.

Type safety

SDK method names and request shapes come from the published OpenAPI contract. TypeScript ships generated .d.ts definitions for editor completion. Each language uses its own response and error pattern, as shown in the examples above. Inspect complete field shapes in the API reference.

typescript
// TypeScript knows sign must be one of the 12 zodiac signs
const { data, error } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'aries' }, // autocompletes all 12 options
});
if (error) throw error;

// after the error check, data is typed, no manual casting needed
console.log(data.date);     // string
console.log(data.overview); // string

You can also import individual namespace classes or response types:

typescript
import { Astrology, type GetAstrologyHoroscopeBySignDailyResponse } from '@roxyapi/sdk';

PHP uses named arguments for parameters and returns decoded JSON. Follow the PHP examples above for reading responses and handling errors.

Gotchas

Parameters are structured

TypeScript always uses { path: {...} }, { body: {...} }, or { query: {...} }. Python uses keyword arguments only (sign="aries"), never positional. PHP uses named arguments (sign: 'aries'), never positional. C# path params are indexers (roxy.Astrology.Horoscope["aries"]), query params go through a config lambda (c => c.QueryParameters.Q = "London, UK"), and POST bodies use a target-typed new() { ... }. Do not mix the patterns.

Timezone accepts both IANA and decimal

Chart endpoints accept timezone as either a decimal (-5, 1, 0) or an IANA identifier ("America/New_York", "Europe/London"). IANA is preferred because it is DST-resolved against the request's date, so historical birth charts pick the correct offset even when you geocoded the city today. Both city.timezone and city.utcOffset from the Location response work. In C# the timezone is a union wrapper, new() { Double = 5.5 } for the decimal offset or new() { String = "Europe/London" } for the IANA identifier.

Location returns an envelope, not a bare array

data.cities[0] in TypeScript and result["cities"][0] in Python. The top-level object carries total, limit, offset for pagination. Same envelope pattern applies to tarot.listCards (data.cards), iching.listHexagrams (data.hexagrams), dreams.searchDreamSymbols (data.symbols), and crystals.searchCrystals / getCrystalsByZodiac / getCrystalsByChakra (data.crystals).

Date format is YYYY-MM-DD, time is HH:MM:SS

These are the JSON request formats. 14:30 is also accepted, with seconds defaulting to 00. Missing required date or time fields and out-of-range values return 400. Use the request types shown in the examples for your SDK.

Do not guess method names

Type roxy.domain. and let autocomplete show methods. Names come from operationId in the OpenAPI spec, not URL paths. Examples: getDailyHoroscope (not dailyHoroscope), calculateLifePath (not lifePath), castCelticCross (not celticCross).

Chart endpoints need coordinates

Use the location API to geocode cities before any birth chart, synastry, panchang, KP, or natal method. Never hardcode a user's latitude, longitude, or timezone from memory.

Do not expose API keys client-side

Call RoxyAPI with a secret key from server code, API routes, serverless functions, or background workers only. Any secret key shipped to the browser is a leaked key; browser code takes a publishable pk_ key.

Do not use raw fetch or requests

The SDK handles auth headers, base URL, SDK identification, and typed responses. Raw HTTP clients re-invent this and miss the type safety.

Python errors raise RoxyAPIError, PHP throws RoxyApiException

Catch and switch on e.code (Python, against ErrorCode) or $e->code() (PHP, an ErrorCode case), not the human-readable message text. .NET throws RoxyError; switch on e.Code against ErrorCodes. Go compares rerr.Code with the roxyapi.ErrCode... constants. The codes are stable between releases; the message text may change.

TypeScript data and error are mutually exclusive

If error is set, data is undefined. Always check error first.

Render the response in the browser

For projects that need to display the response visually (charts, tables, cards, forms) without writing your own SVG geometry or table layouts, install RoxyAPI UI alongside the SDK.

bash
npm install @roxyapi/ui @roxyapi/sdk

Components are stateless. Caller fetches via the SDK, passes the response as the data prop. Theming via CSS custom properties on :root or per element. Works in React, Next.js, Vue, Svelte, Angular, vanilla HTML, and WordPress.

tsx
'use client';

import { createRoxy, type NatalChartResponse } from '@roxyapi/sdk';
import { RoxyNatalChart, RoxyLocationSearch } from '@roxyapi/ui-react';
import { useState } from 'react';

const roxy = createRoxy(process.env.NEXT_PUBLIC_ROXY_API_KEY!);

export default function Page() {
  const [chart, setChart] = useState<NatalChartResponse | null>(null);

  const onLocationSelect = async (e: CustomEvent<{ latitude: number; longitude: number; timezone: string }>) => {
    const { data, error } = await roxy.astrology.generateNatalChart({
      body: { date: '1990-01-15', time: '14:30:00', ...e.detail },
    });
    if (error) throw error;
    setChart(data);
  };

  return (
    <>
      <RoxyLocationSearch onroxy-location-select={onLocationSelect} />
      {chart && <RoxyNatalChart data={chart} />}
    </>
  );
}

This component runs in the browser, so give it a publishable pk_ key, the key class made to ship in web pages. See publishable keys.

Full setup walkthrough at /docs/ui, catalog and live customizer at /ui. Source on GitHub at RoxyAPI/ui, MIT licensed, published with SLSA provenance via OIDC.

AI coding agents

The TypeScript, Python, PHP, C#, Go, and Rust SDKs bundle a consumer AGENTS.md. Point your coding agent at the installed guide explicitly: node_modules/@roxyapi/sdk/AGENTS.md, the installed Python package, vendor/roxyapi/sdk/AGENTS.md, the restored NuGet package (~/.nuget/packages/roxyapi.sdk/<version>/AGENTS.md), the Go module cache, or the roxyapi-<version>/AGENTS.md file in the Cargo registry source cache after cargo fetch.

  • Quickstart, critical patterns, common tasks reference, gotchas
  • Field format table covering timezone decimals, date / time strings, nested person objects, enum values
  • MCP tool name mapping for every REST endpoint

Before the package is installed, an agent reads the same guide as raw markdown. Fetch it whole with curl -s, not a summarizing web tool:

For agents in projects WITHOUT any SDK installed (Ruby, raw curl, Bash), there is also a site-level AGENTS.md playbook at https://roxyapi.com/AGENTS.md covering the same Rule 0, common tasks, body shapes, error contract, and field gotchas, but language-agnostic.

Also available: a remote MCP server per domain at https://roxyapi.com/mcp/{domain} (Streamable HTTP, no stdio / no self-hosting) for agents that speak the Model Context Protocol.