# Biorhythm API, what to build and how to call it

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

Biorhythm is the fastest domain to wire up because every call needs just a birth date. 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.

## What you can build

- Daily energy check-in features for wellness and habit apps
- Mood and productivity planners that highlight high and low days
- Couples compatibility cards for dating and relationship apps
- Critical-day alerts for scheduling and calendar tools
- Lightweight phase widgets for dashboards and status bars

## Prerequisites

1. A Roxy API key. Get one on the [pricing page](/pricing).
2. Nothing else. No coordinates, no birth time, no account sync.

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
composer require roxyapi/sdk
```

Set the API key once at SDK construction. Detailed setup in [SDK install + usage](/docs/sdk).

## Call the endpoint

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


### curl
```bash
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"}'
```

### TypeScript SDK
```typescript
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);
```

### Python SDK
```python
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 SDK
```php
<?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'];
```

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

Then ask Claude, "what is the biorhythm reading for July 15 1990 today?" The agent calls the right tool and returns the energy rating and advice. This is Remote MCP over Streamable HTTP, no local process to run. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp).

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](/docs/sdk).

## Render the result

Skip building the chart layer. `<roxy-biorhythm-chart>` from [@roxyapi/ui](/docs/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.

```html
<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.

```tsx
'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`](/api-reference#tag/biorhythm/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.

```bash
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"}'
```

### Forecast, the planner upsell

[`POST /biorhythm/forecast`](/api-reference#tag/biorhythm/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`. This powers calendars and scheduling tools that need forward-looking data.

### Critical days, the alert feature

[`POST /biorhythm/critical-days`](/api-reference#tag/biorhythm/POST/biorhythm/critical-days) scans a range up to 180 days for zero-crossing days, returning each `date`, `cycle`, `direction`, `severity`, and an `advisory`. Use it to flag low-stability days before they arrive.

### Compatibility, the dating-app bolt-on

[`POST /biorhythm/compatibility`](/api-reference#tag/biorhythm/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`](/api-reference#tag/biorhythm/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](/api-reference#tag/biorhythm).

## Gotchas

- **Birth date is the only required field.** `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 transition or low-stability days, not warnings, to keep the tone supportive.

## What to build next

Biorhythm pairs naturally with the [Forecast API](/docs/guides/forecast), 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](/docs/sdk), and for multi-domain conversational patterns see the [AI chatbot tutorial](/docs/tutorials/ai-chatbot). Product overview at [/products/biorhythm-api](/products/biorhythm-api).