Forecast API that merges upcoming transit aspects, sign ingresses, retrograde stations, new and full moons, biorhythm critical days, and Vimshottari dasha changes into one time-ordered forecast for a single subject. The only cross-domain forecast timeline behind one key, positions verified against NASA JPL Horizons, available over Remote MCP with typed SDKs. Horizon capped at 90 days.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/roxyapi-forecast-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Roxy Forecast API
version: 2.0.0
description: '# RoxyAPI: AI-Native Insight Infrastructure
> **Base URL:** `https://roxyapi.com/api/v2`
> All endpoint paths below are relative to this base URL.'
contact:
name: RoxyAPI Support
url: https://roxyapi.com/contact
license:
name: Proprietary
url: https://roxyapi.com/policy/terms
servers:
- url: /api/v2
description: Production API v2
security:
- apiKey: []
tags:
- name: Forecast
description: Forecast API that merges upcoming transit aspects, sign ingresses, retrograde stations, new and full moons, biorhythm critical days, and Vimshottari dasha changes into one time-ordered forecast for a single subject. The only cross-domain forecast timeline behind one key, positions verified against NASA JPL Horizons, available over Remote MCP with typed SDKs. Horizon capped at 90 days.
paths:
/forecast/timeline:
post:
operationId: generateTimeline
tags:
- Forecast
summary: Cross-domain forecast timeline - Transits, ingresses, stations, dasha changes…
description: 'Build one time-ordered forecast for a single birth subject by merging upcoming events across three domains: western transit-to-natal aspects, sign ingresses, retrograde stations, eclipses, and new and full moons; biorhythm critical days; and vedic Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. The window is clamped to 90 days and events are capped and scored by significance. Built for what-is-coming dashboards, daily and weekly forecast feeds, and timing tools.'
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
requestBody:
content:
application/json:
schema:
type: object
properties:
birthData:
type: object
properties:
date:
type: string
format: date
example: '1990-07-15'
description: Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
time:
type: string
format: time
example: '13:30:00'
description: Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
timezone:
anyOf:
- type: number
minimum: -14
maximum: 14
- type: string
description: 'IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.'
example: America/New_York
latitude:
type: number
minimum: -90
maximum: 90
default: 0
example: 0
description: Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
longitude:
type: number
minimum: -180
maximum: 180
default: 0
example: 0
description: Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
required:
- date
- time
- timezone
description: The single birth subject this forecast is built for. One object only, never an array.
startDate:
type: string
format: date
example: '2026-06-01'
description: First day of the forecast window in YYYY-MM-DD format. Defaults to today in UTC.
endDate:
type: string
format: date
example: '2026-08-30'
description: Last day of the forecast window in YYYY-MM-DD format. Defaults to startDate plus 30 days. The window is clamped to a maximum of 90 days from startDate.
domains:
type: array
items:
type: string
enum:
- western
- vedic
- biorhythm
example: western
description: Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days.
example:
- western
- vedic
- biorhythm
description: Which forecast domains to include. Defaults to all three. Pass a subset to scope the timeline to one or two engines.
minSignificance:
type: number
minimum: 0
maximum: 100
example: 0
description: Drop events scoring below this significance threshold from 0 to 100. Defaults to 0, keeping all events.
domainWeights:
type: object
properties:
western:
type: number
minimum: 0
maximum: 100
example: 1.5
description: Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
vedic:
type: number
minimum: 0
maximum: 100
example: 1.5
description: Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
biorhythm:
type: number
minimum: 0
maximum: 100
example: 1.5
description: Multiplier for this domain significance. 1 leaves it unchanged, above 1 promotes the domain, below 1 demotes it.
example:
vedic: 1.5
biorhythm: 0.5
description: Per-domain significance multipliers applied before the significance floor and event cap. Bias which domains survive filtering and the cap. Omitted domains default to a weight of 1. Valid keys are western, vedic, and biorhythm.
required:
- birthData
responses:
'200':
description: Merged forecast timeline with time-ordered events across the requested domains
content:
application/json:
schema:
type: object
properties:
birthData:
type: object
properties:
date:
type: string
format: date
example: '1990-07-15'
description: Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
time:
type: string
format: time
example: '13:30:00'
description: Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
timezone:
type: number
example: -4
description: Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the DST-correct offset for the birth date, so this is the literal number applied, never the name.
latitude:
type: number
minimum: -90
maximum: 90
default: 0
example: 0
description: Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
longitude:
type: number
minimum: -180
maximum: 180
default: 0
example: 0
description: Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
required:
- date
- time
- timezone
description: Echo of the birth subject this forecast was built for.
startDate:
type: string
example: '2026-06-01'
description: First day of the resolved forecast window.
endDate:
type: string
example: '2026-08-30'
description: Last day of the resolved forecast window after the horizon clamp.
count:
type: number
example: 42
description: Number of events in the timeline after deduplication, filtering, and the event cap.
events:
type: array
items:
type: object
properties:
date:
type: string
example: '2026-07-04'
description: Calendar date of the event in YYYY-MM-DD (UTC).
datetime:
type: string
example: '2026-07-04T08:42:11Z'
description: Exact instant of the event as an ISO-8601 UTC datetime. Astronomical events are refined to this instant by search, not reported at a daily sample point.
domain:
type: string
enum:
- western
- vedic
- biorhythm
example: western
description: Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language.
type:
type: string
enum:
- transit-aspect
- sign-ingress
- retrograde-station
- eclipse
- lunar-phase
- dasha-change
- critical-day
example: transit-aspect
description: Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language.
body:
type: string
example: Saturn
description: Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, a mahadasha, antardasha, or pratyantardasha label for dasha changes, or the critical cycle for biorhythm days.
target:
type: string
example: Moon
description: For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types.
aspect:
type: string
example: square
description: For a transit-aspect, the angular relationship. One of conjunction, sextile, square, trine, opposition. Absent for other event types.
orb:
type: number
example: 0.12
description: For a transit-aspect, the separation in degrees from the exact aspect at the reported instant. Tighter orb means a more exact and significant aspect.
station:
type: string
enum:
- retrograde
- direct
example: retrograde
description: For a retrograde-station, whether the planet turns retrograde or direct. A stable machine value, never localized. Absent for other event types.
kind:
type: string
enum:
- penumbral
- partial
- annular
- total
example: total
description: For an eclipse, its classification. total and penumbral apply to lunar eclipses, partial applies to both, annular and total apply to solar eclipses. A stable machine value, never localized. Absent for other event types.
obscuration:
type: number
example: 0.966
description: For a lunar eclipse, the peak fraction from 0 to 1 of the Moon disc covered by Earth umbra. 1 for a total lunar eclipse, between 0 and 1 for a partial, 0 for a penumbral. Absent for solar eclipses and other event types.
phase:
type: string
enum:
- new-moon
- full-moon
example: full-moon
description: 'For a lunar-phase event, which syzygy it is: new-moon (Sun-Moon conjunction) or full-moon (Sun-Moon opposition). The intermediate quarters are not emitted. A stable machine value, never localized. Absent for other event types.'
description:
type: string
example: Transiting Saturn square natal Moon, an exact aspect within 0.12 degrees.
description: 'Plain-language summary of the event, suitable for direct display. The only localized field: when lang is set this sentence, and the body, target, and aspect names within it, render in the requested language while the structured fields stay English.'
significance:
type: number
example: 90
description: Importance score from 0 to 100. Outer-planet exact transit aspects and mahadasha changes score highest; fast Moon events and biorhythm critical days score lower. When domainWeights is supplied this is the weighted score, rounded and clamped to 0 to 100, which is the same value the significance floor and the event cap acted on.
required:
- date
- datetime
- domain
- type
- body
- description
- significance
description: The merged, time-ordered forecast events across the requested domains.
required:
- birthData
- startDate
- endDate
- count
- events
'400':
description: Validation error. `issues[]` lists every failed field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: First issue summary.
code:
type: string
enum:
- validation_error
issues:
type: array
description: Every validation failure. Use this to rebuild a valid request.
items:
type: object
properties:
path:
type: string
description: Dot-separated field path, or "(root)" for top-level.
message:
type: string
code:
type: string
description: Zod issue code (invalid_type, too_small, too_big, invalid_string, ...).
expected:
type: string
description: Expected type for invalid_type.
minimum:
description: Minimum bound for too_small issues.
oneOf:
- type: number
- type: string
maximum:
description: Maximum bound for too_big issues.
oneOf:
- type: number
- type: string
inclusive:
type: boolean
format:
type: string
description: Format name for string issues (regex, email, url, uuid).
pattern:
type: string
description: Regex pattern when format is regex.
required:
- path
- message
required:
- error
- code
- issues
'401':
description: Invalid or missing API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'405':
description: Method not allowed. The path exists but only responds to the methods listed in `allow[]` and the `Allow` response header.
headers:
Allow:
description: Comma-separated list of allowed methods (RFC 9110).
schema:
type: string
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
enum:
- method_not_allowed
allow:
type: array
items:
type: string
description: Allowed HTTP methods for this path. Mirrors the Allow response header.
docs:
type: string
description: Link to the product page for this domain.
required:
- error
- code
- allow
'429':
description: Monthly rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Human-readable error message. May change wording.
code:
type: string
description: Machine-readable error code. Stable identifier.
required:
- error
- code
/forecast/transits:
post:
operationId: forecastTransits
tags:
- Forecast
summary: Western astrology forecast - aspects, ingresses, stations, eclipses, moon phases
description: 'Forecast the western astrology events for a single birth chart over a window up to 90 days: every transit-to-natal major aspect refined to its exact instant, every transiting planet sign ingress, every retrograde or direct station, every solar and lunar eclipse, and every New and Full Moon. Returns a time-ordered, significance-scored timeline. Built for astrology forecast feeds, transit alerts, and timing tools.'
security:
- apiKey: []
parameters:
- schema:
type: string
enum:
- en
- tr
- de
- es
- hi
- pt
- fr
- ru
- zh-Hans
- zh-Hant
default: en
example: en
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
required: false
description: 'Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English.'
name: lang
in: query
requestBody:
content:
application/json:
schema:
type: object
properties:
birthData:
type: object
properties:
date:
type: string
format: date
example: '1990-07-15'
description: Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
time:
type: string
format: time
example: '13:30:00'
description: Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
timezone:
anyOf:
- type: number
minimum: -14
maximum: 14
- type: string
description: 'IANA name (e.g. "America/New_York", "Europe/London", "UTC"), decimal hours (e.g. -5 for EST, 1 for CET), or a fixed UTC offset (e.g. "-05:00", "+01:00"). Prefer the IANA name: it is resolved to the DST-correct offset for the birth date, while a fixed offset or decimal is taken literally and will be wrong if it does not match the daylight-saving state on that date. Invalid timezones return 400 with a validation error.'
example: America/New_York
latitude:
type: number
minimum: -90
maximum: 90
default: 0
example: 0
description: Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
longitude:
type: number
minimum: -180
maximum: 180
default: 0
example: 0
description: Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
required:
- date
- time
- timezone
description: The single birth subject this transit forecast is built for. One object only, never an array.
startDate:
type: string
format: date
example: '2026-06-01'
description: First day of the transit window in YYYY-MM-DD format. Defaults to today in UTC.
endDate:
type: string
format: date
example: '2026-08-30'
description: Last day of the transit window in YYYY-MM-DD format. Defaults to startDate plus 30 days. Clamped to a maximum of 90 days from startDate.
minSignificance:
type: number
minimum: 0
maximum: 100
example: 0
description: Drop transit events scoring below this significance threshold from 0 to 100. Defaults to 0.
required:
- birthData
responses:
'200':
description: 'Time-ordered western forecast events: aspects, ingresses, stations, eclipses, and moon phases'
content:
application/json:
schema:
type: object
properties:
birthData:
type: object
properties:
date:
type: string
format: date
example: '1990-07-15'
description: Birth date in YYYY-MM-DD format. Anchors the natal chart and the Vimshottari dasha sequence.
time:
type: string
format: time
example: '13:30:00'
description: Birth time in 24-hour HH:MM:SS format. Precision matters for the natal positions the transit aspects are measured against.
timezone:
type: number
example: -4
description: Decimal UTC offset the forecast was computed with, resolved from whatever the request sent. An IANA name is resolved to the DST-correct offset for the birth date, so this is the literal number applied, never the name.
latitude:
type: number
minimum: -90
maximum: 90
default: 0
example: 0
description: Birth latitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
longitude:
type: number
minimum: -180
maximum: 180
default: 0
example: 0
description: Birth longitude in decimal degrees. Optional and does not affect the timeline. Defaults to 0.
required:
- date
- time
- timezone
description: Echo of the birth subject this forecast was built for.
startDate:
type: string
example: '2026-06-01'
description: First day of the resolved forecast window.
endDate:
type: string
example: '2026-08-30'
description: Last day of the resolved forecast window after the horizon clamp.
count:
type: number
example: 42
description: Number of events in the timeline after deduplication, filtering, and the event cap.
events:
type: array
items:
type: object
properties:
date:
type: string
example: '2026-07-04'
description: Calendar date of the event in YYYY-MM-DD (UTC).
datetime:
type: string
example: '2026-07-04T08:42:11Z'
description: Exact instant of the event as an ISO-8601 UTC datetime. Astronomical events are refined to this instant by search, not reported at a daily sample point.
domain:
type: string
enum:
- western
- vedic
- biorhythm
example: western
description: Forecast domain. western covers transit aspects, sign ingresses, retrograde stations, eclipses, and new and full moons. vedic covers Vimshottari mahadasha, antardasha, and pratyantardasha boundaries. biorhythm covers critical days. A stable machine value, never localized, so consumers can branch on it under any language.
type:
type: string
enum:
- transit-aspect
- sign-ingress
- retrograde-station
- eclipse
- lunar-phase
- dasha-change
- critical-day
example: transit-aspect
description: Event kind. transit-aspect, sign-ingress, retrograde-station, eclipse, and lunar-phase are western, dasha-change is vedic Vimshottari, critical-day is biorhythm. A stable machine value, never localized, so consumers can branch on it under any language.
body:
type: string
example: Saturn
description: Primary subject of the event. A transiting planet for western events, Sun for a solar eclipse, Moon for a lunar eclipse or a new or full moon, a mahadasha, antardasha, or pratyantardasha label for dasha changes, or the critical cycle for biorhythm days.
target:
type: string
example: Moon
description: For a transit-aspect, the natal body the transit aspects. For a sign-ingress, the zodiac sign entered, and for a lunar-phase, the zodiac sign of the New or Full Moon. Absent for other event types.
aspect:
type: string
example: square
des
# --- truncated at 32 KB (117 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/roxyapi/refs/heads/main/openapi/roxyapi-forecast-api-openapi.yml