Biorhythm API guide

Ship a daily energy check-in, a multi-day forecast, or a couples compatibility card. Birth date only. No birth time, no location, no geocoding.

Biorhythm is the fastest domain to wire up because birth-date calculations need no time or location; the daily endpoint uses a seed instead. The API turns that date into ten named cycles with phase detection, an energy rating, and editorial interpretation text you never have to write. It sits inside the same subscription as every other RoxyAPI domain, so one key covers biorhythm plus astrology, numerology, tarot, and the rest, with flat all-inclusive pricing and no per-request fees.

Biorhythm curves are a belief-based mathematical model for entertainment and reflection. Calculation accuracy does not establish predictions of health, ability or risk. Do not use cycle scores to schedule medical care, emergency work or financial decisions. Research has found no support for the proposed behavioral or accident predictions: review of biorhythm theory and trauma-patient study.

What you can build

• Daily energy check-in features for wellness and habit apps
• Reflective journals that label high and low model values
• Couples compatibility cards for dating and relationship apps
• Zero-crossing markers in an optional calendar overlay
• Lightweight phase widgets for dashboards and status bars

Prerequisites

1. A RoxyAPI key. Get your API key.
2. Nothing else. No coordinates, no birth time, no account sync.

Install

npm install @roxyapi/sdk

pip install roxy-sdk

composer require roxyapi/sdk

dotnet add package RoxyApi.Sdk

Set the API key once at SDK construction. Detailed setup in SDK install + usage.

Call the endpoint

The core call is a full reading for a birth date and target date. Pick a language tab and paste.

curl -X POST https://roxyapi.com/api/v2/biorhythm/reading \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birthDate": "1990-07-15", "targetDate": "2026-06-07"}'

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

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

const { data } = await roxy.biorhythm.getReading({
  body: { birthDate: '1990-07-15', targetDate: '2026-06-07' },
});

console.log(data.energyRating);              // 9
console.log(data.overallPhase);              // "high_energy"
console.log(data.cycles.physical.value);     // 27
console.log(data.advice);

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

result = roxy.biorhythm.get_reading(birth_date='1990-07-15', target_date='2026-06-07')
print(result['energyRating'])
print(result['overallPhase'])
print(result['cycles']['physical']['value'])

<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$result = $roxy->biorhythm->getReading(birthDate: '1990-07-15', targetDate: '2026-06-07');
echo $result['energyRating'];
echo $result['overallPhase'];
echo $result['cycles']['physical']['value'];

using RoxyApi;
using Microsoft.Kiota.Abstractions; // for the Date and Time types

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

var result = await roxy.Biorhythm.Reading.PostAsync(new()
{
    BirthDate = new Date(1990, 7, 15),
    TargetDate = new Date(2026, 6, 7),
});

Console.WriteLine(result!.EnergyRating);  // 9
Console.WriteLine(result.OverallPhase);   // "high_energy"
Console.WriteLine(result.Advice);

claude mcp add-json --scope user roxy-biorhythm '{"type":"http","url":"https://roxyapi.com/mcp/biorhythm","headers":{"X-API-Key":"YOUR_KEY"}}'

The response includes daysSinceBirth, an energyRating from 1 to 10, an overallPhase, a top-level interpretation and advice, a criticalAlerts array, and a cycles object. Each cycle (physical, emotional, intellectual, intuitive, aesthetic, awareness, spiritual, passion, mastery, wisdom) carries value, phase, phaseLabel, dayInCycle, daysUntilCritical, trend, and an interpretation. You never have to write any interpretation text.

If your app serves other languages, add ?lang=hi (or de, es, fr, pt, ru, tr) to translate the interpretation fields. See i18n.

Render the result

Skip building the chart layer. <roxy-biorhythm-chart> from @roxyapi/ui draws daily bars, forecast cycle lines, or critical days, switched by the mode attribute. Fetch on your server so the key never reaches the browser, then pass the unwrapped data to the component.

<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0/dist/cdn/roxy-ui.js" defer></script>
<roxy-biorhythm-chart id="b" mode="forecast"></roxy-biorhythm-chart>
<script type="module">
  document.getElementById('b').data = forecastResponse;
</script>

In React the same component is RoxyBiorhythmChart with a typed mode prop ('daily' | 'forecast' | 'critical-days'). Pass the unwrapped SDK response, not the full { data, error } envelope.

'use client';
import { RoxyBiorhythmChart } from '@roxyapi/ui-react';
import type { PostBiorhythmForecastResponse } from '@roxyapi/sdk';

export function BiorhythmChart({ data }: { data: PostBiorhythmForecastResponse }) {
  return <RoxyBiorhythmChart data={data} mode="forecast" />;
}

Want full control of the markup? The response is plain JSON, build whatever you like.

Ship the rest

Daily check-in, the seeded hook

POST /biorhythm/daily returns a seeded reading for a "biorhythm of the day" feature. Same seed plus same date always produces the same reading, so push notifications and morning briefings stay consistent per user. It returns energyRating, overallPhase, a spotlight on one featured cycle, a quickRead of the three primary cycles, a dailyMessage, and advice. Pass any unique id as the seed.

curl -X POST https://roxyapi.com/api/v2/biorhythm/daily \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed": "user123", "date": "2026-06-07"}'

This daily reading is not calculated from a birth date. Its primary cycle values depend on the date; the seed selects the spotlight cycle. Different seeds can select the same spotlight, so do not promise a unique reading to every user. Use /reading when the feature needs birth-date-based curves.

Keep a notification and widget in sync

For an opted-in daily reminder, let a backend job choose the intended reading date and call /daily with a stable, non-sensitive seed and the response language. Store the response in your application cache, then send a neutral check-in notification linked to that date. The widget should load that saved reading when the user opens the notification, including after midnight. Keep the date, seed, and language together; do not silently substitute the current date. The API defaults an omitted date to UTC today, so an app promising a local morning check-in must choose its dates and delivery times deliberately.

Show energyRating and overallPhase first, then spotlight.message and the three quickRead values. Label them as model output. Offer the full ten-cycle /reading view separately when a user provides a birth date. Save the complete response for a reading journal that must survive future implementation changes. A server response cache does not replace this application storage or make repeated API calls free; see caching and cost.

Forecast, the planner upsell

POST /biorhythm/forecast returns daily cycle values across a date range up to 90 days, plus a summary with bestDay, worstDay, criticalDayCount, averageEnergy, and periodAdvice. These names rank the mathematical model values, not the best or worst days for actual activities. Use them for an optional calendar display.

Critical days, the alert feature

POST /biorhythm/critical-days scans a range up to 180 days for zero-crossing days, returning each date, cycle, direction, severity, and an advisory. Display these as model zero crossings, without implying instability or accident risk.

Compatibility, the dating-app bolt-on

POST /biorhythm/compatibility overlays two birth dates on a target date and returns per-cycle alignment, an overallScore from 0 to 100, a rating label, strengths, challenges, advice, and a dailySync snapshot.

Phases, the lightweight widget

POST /biorhythm/phases returns the current phase of all ten cycles without the long interpretation payload. Ideal for dashboards and status bars that need a quick read.

See the full list at the Biorhythm API reference.

Build with a coding or conversational agent

For Cursor, start with the Cursor setup guide so the coding agent can search the reference and verify fields before scaffolding the dashboard. Keep the secret key in your backend, check API errors before rendering, and verify one real reading before adding notifications or saved history. Use the chart component above instead of asking the agent to recreate the cycle display.

A conversational agent connects to the Biorhythm Remote MCP server. Discover its tool names and input schemas from the server instead of guessing them from SDK method names. Choose a seeded daily reading for a birth-date-free check-in, a full reading or forecast for supplied birth data, phases for a compact display, and compatibility only when both birth dates are available. Ask for missing inputs rather than inventing them.

Your app owns conversation history, reminder consent, and background jobs. Summarize returned values as an entertainment or reflection model; do not turn an energy score into instructions about workouts, work capacity, medical care, or consequential decisions. Grounding supplies data but does not guarantee that generated prose will stay within those limits.

Gotchas

• Birth-date calculations need birthDate. The /daily endpoint instead accepts a seed and date. targetDate, date, startDate, and endDate default to today in UTC when omitted. Pass them to view past or future dates.
• Energy rating runs 1 to 10. overallPhase gives the named state (for example high_energy or recovery). Surface both. Users read the number first.
• Forecast range caps at 90 days, critical days at 180. Requests beyond the cap are rejected. Page through longer windows.
• Seeds make daily readings reproducible. Same seed plus same date returns the same reading. The server appends the date to your seed internally, so pass a stable per-user id and let the date vary.
• Critical days are zero-crossings, not bad days. Frame them as mathematical transitions, without predicting mood, ability or risk.

What to build next

Biorhythm pairs naturally with the Forecast API, which merges biorhythm critical days with astrology and Vedic timing into one timeline. For typed calls across every domain on one key, see the SDK guide, and for multi-domain conversational patterns see the AI chatbot tutorial. Product overview at /products/biorhythm-api.