RoxyAPI
Quick StartPlaygroundSDKMCP SetupFree TemplatesAGENTS.md
  1. Docs
  3. Build With Roxy
  5. SDK (TypeScript / Python / PHP)

SDK (TypeScript / Python / PHP / WordPress)

Official Roxy SDKs for TypeScript, Python, and PHP, plus a WordPress plugin with Gutenberg blocks and shortcodes. Full type safety and IDE autocomplete on every code SDK, drop-in shortcodes on WordPress, all hitting the same 145+ endpoints across 12 domains. Same API shape, same domain names, three languages. Drop a composer require, pip install, or npm install into any Laravel, Symfony, Slim, Django, FastAPI, Next.js, or Express project and ship a natal-chart endpoint in five minutes.

Install

npm install @roxyapi/sdk

Quick start

Two lines to instantiate, one line per API call. createRoxy / create_roxy / RoxyAPI\Sdk\createRoxy set the base URL, auth header, and SDK identification header automatically.

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 API key in client-side code. Call Roxy from your server, API routes, serverless functions, or background workers only.

Authentication

Pass your API key on initialization. Get your API key at roxyapi.com/pricing, delivered instantly after checkout.

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

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

Domains

Each domain is a namespace on the roxy instance. TypeScript returns typed objects via { data, error, response } per call. Python and PHP return the decoded JSON directly as associative arrays / dicts. Python raises RoxyAPIError on failure; PHP throws RoxyApiException (catch it and switch on $e->errorCode).

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.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. Either form works on chart endpoints — pass the IANA string for DST-correct historical charts, or the utcOffset decimal if you prefer numbers.

const { data } = await roxy.location.searchCities({
  query: { q: 'Mumbai, India' },
});

// 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 "Asia/Kolkata" — server resolves DST for the chart date
  },
});

Chart endpoints accept timezone as either a decimal number (5.5 for IST, -5 for EST, 9 for Tokyo) or an IANA identifier ("Asia/Kolkata", "America/New_York"). 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

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

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

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.

const { data } = await roxy.vedicAstrology.generateBirthChart({
  body: {
    date: '1990-01-15',
    time: '14:30:00',
    latitude: 28.6139,
    longitude: 77.209,
    timezone: 5.5,
  },
});

// 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

const { data } = await roxy.astrology.generateNatalChart({
  body: {
    date: '1990-01-15',
    time: '14:30:00',
    latitude: 28.6139,
    longitude: 77.209,
    timezone: 5.5,
  },
});

console.log(data.planets.length);  // 13 (incl. 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

const { data } = await roxy.tarot.getDailyCard({ body: { seed: 'user-123' } });
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

const { data } = await roxy.angelNumbers.getAngelNumber({
  path: { number: '1111' },
});
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

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

Multi-language responses

Interpretations are available in eight languages: English (en), Turkish (tr), German (de), Spanish (es), French (fr), Hindi (hi), Portuguese (pt), Russian (ru).

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

Supported: astrology, vedicAstrology / vedic_astrology, numerology, tarot, biorhythm, iching, crystals, angelNumbers / angel_numbers. English-only: dreams, location, usage.

Async support

TypeScript is async by default (every method returns a Promise). Python ships an _async variant for every sync method, for asyncio, FastAPI, or any event loop. PHP is synchronous per call; for concurrent fan-out (e.g. fetching 12 horoscopes in parallel) use the Saloon connector's request pool — see the PHP SDK README for examples.

// 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. All three expose a stable code / errorCode field you can branch on.

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

if (error) {
  switch (error.code) {
    case 'validation_error':
      console.error('Bad input:', error.error);
      break;
    case 'rate_limit_exceeded':
      console.error('Monthly quota reached');
      break;
    default:
      console.error('API error:', error.code, error.error);
  }
} else {
  console.log(data.answer); // "Yes" | "No" | "Maybe"
}

Error codes

StatusCodeWhen
400validation_errorMissing or invalid parameters. Check issues[] for per-field failures.
401api_key_requiredNo API key provided
401invalid_api_keyKey format invalid or tampered
401subscription_not_foundKey references non-existent subscription
401subscription_inactiveSubscription cancelled, expired, or suspended
404not_foundResource does not exist
429rate_limit_exceededMonthly request quota reached
500internal_errorServer error

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

Type safety

Every SDK is fully typed for its language. TypeScript ships generated .d.ts definitions. PHP ships PHPDoc on every Saloon Request class plus a phpstan-level-8-clean public surface. Python ships py.typed for mypy and Pyright.

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

// 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:

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

PHP uses named arguments (PHP 8.0+) for parameters and PHPDoc-typed Saloon Request classes for response shapes. PhpStorm, VS Code (Intelephense), and phpstan all see the full signature without any extra setup.

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. Do not mix the patterns.

Timezone accepts both IANA and decimal

Chart endpoints accept timezone as either a decimal (5.5, -5, 0) or an IANA identifier ("Asia/Kolkata", "America/New_York"). 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.

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

Both are strings. Time must include seconds, 14:30 will be rejected.

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 Roxy from server code, API routes, serverless functions, or background workers only. Any key shipped to the browser is a leaked 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) or $e->errorCode (PHP), not the human-readable message text. 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 Roxy UI alongside the SDK.

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.

'use client';

import { createRoxy } 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(null);

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

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

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

All three SDKs ship AGENTS.md bundled in the package so AI agents (Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI) read it directly from node_modules/@roxyapi/sdk/AGENTS.md, the installed Python package, or vendor/roxyapi/sdk/AGENTS.md.

  • 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

For agents in projects WITHOUT any SDK installed (Go, Ruby, Rust, 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.