What is the Multi-Year Transit Roadmap API?

It is a single endpoint, POST /api/v3/pdf/multi-year-roadmap-report, that turns a birth chart into a ~28-page A4 PDF forecasting the next three to five years. The report includes outer-planet life chapters, transit activation windows, annual profections, a Firdaria overlay, a monthly intensity calendar, convergence detection, a decision matrix, and Best Days to Act. The full 5-year scan runs in about 1.4 seconds.

How many years does it forecast?

Between three and five years, set by the years field in the request. You can offer a shorter three-year forecast on a lower tier and the full five years on a premium plan. The scan runs forward from the request date across whichever range you choose.

What does the response look like?

The endpoint returns application/pdf, a finished ~28-page A4 portrait document. You do not get raw JSON to lay out yourself. You can stream it to a user as a download, email it, or store it. The layout, charts, and tables are already rendered.

What is a station-aware transit peak?

A transit does not hit at a single instant; it builds, peaks, and fades, and retrogrades can make a planet cross the same point several times. Station-aware peaks mark the exact date a transit is strongest instead of giving a vague multi-month span, using the timing engine's station data so retrograde activations are placed correctly.

How do the life chapters work?

The report uses outer-planet sign ingresses, when Jupiter, Saturn, Uranus, Neptune, or Pluto changes sign, as chapter dividers. Those shifts reshape the tone of a stretch of time, so the forecast reads as a sequence of chapters rather than a flat list of dates. It gives the document a narrative arc users come back to.

What are the annual profection briefings?

Profections move the focus one house per year, birthday to birthday. Each year of the forecast gets a briefing naming the profected house and its ruling planet, which sets that year's theme. It is the layer that tells a user which area of life is in focus, something a plain transit list cannot do.

What is the Firdaria overlay?

Firdaria is a time-lord system that assigns major and minor planetary periods across a life. The roadmap maps those periods over the same forecast span, giving a second, slower-moving track alongside profections. Together they provide the time-lord context that turns raw transits into a reading.

What is convergence detection?

Convergence detection flags the months where a transit window, a profection lord, and a Firdaria period all point at the same area. Those stacked months are the strongest signals in the forecast, because the chart is saying the same thing three different ways. It runs on the /timing/convergence endpoint behind the report.

What is the life-area decision matrix?

It is a quarter-by-area grid. For each life area, it marks which quarters look favorable and which look challenging across the forecast. Someone planning a launch, a move, or a big purchase can read the chart by the area they care about rather than by planet, which makes the report feel like advice.

How fast is the full scan?

About 1.4 seconds for a full five-year scan across 18 natal points. The scan is memoized, so repeat calls for the same chart are even faster. That speed lets you generate the PDF on demand when a user upgrades rather than precomputing reports in a batch job.

What languages are supported?

Nine: English, Russian, German, French, Spanish, Italian, Portuguese, Chinese, and Turkish (en, ru, de, fr, es, it, pt, zh, tr). The language is a top-level field in the request, so you can ship the same forecast product to a global audience from one endpoint.

What does the request body look like?

You send a subject with a name and birth data (year, month, day, hour, minute, city, country_code), a years value between 3 and 5, a top-level language, and a tradition (universal by default). Note that language sits at the top level of the request, not inside the subject object.

Which endpoints run behind the report?

The PDF endpoint calls three public timing endpoints: /api/v3/timing/stations for retrograde peaks, /api/v3/timing/transits for activation windows, and /api/v3/timing/convergence for where layers stack. You can call those directly if you want the raw data, or use the PDF endpoint for the finished document.

Developers and indie SaaS builders running subscription astrology apps, plus astrologer-entrepreneurs productizing annual readings. It is for teams that want to sell a premium year-ahead forecast without building a multi-year scan engine in-house. It is not a beginner explainer of what a transit is.

How much does the Multi-Year Transit Roadmap cost?

The Always Free tier includes 50 requests per month. Starter is $11/month, Professional is $37/month for 55,000 requests, Business is $99/month for 220,000 requests, and Enterprise is $399+/month with unlimited usage and dedicated servers.

Is there a free tier?

Yes. Every account gets 50 free requests per month with no card required, so you can generate full roadmap PDFs against test charts and check the layout, the windows, and the best days before you commit to a paid plan.

What visuals are in the PDF?

The report includes a year-stacked Gantt chart of all transit windows, a monthly intensity heat-map, chapter dividers for the outer-planet life chapters, the life-area decision matrix grid, and a best-days table. The visuals are rendered server-side, so the document is ready to hand to a user as is.

How do I integrate it into my app?

Send one POST request with the subject, years, language, and tradition, then stream the returned PDF to your user or store it. Most teams wire it to an upgrade flow: a user buys the year-ahead tier, you call the endpoint, and the ~28-page forecast comes back in about 1.4 seconds. Pair it with our Solar Return API for a fuller year-ahead bundle.

Multi-Year Transit Roadmap

A 5-Year Forecast PDF That Earns Annual Subscriptions

One POST to /api/v3/pdf/multi-year-roadmap-report returns a ~28-page A4 PDF: outer-planet life chapters, station-aware transit windows to every natal point, annual profection briefings, a Firdaria time-lord overlay, a monthly intensity calendar, convergence detection, a life-area decision matrix, and personalized Best Days to Act.

A full 5-year, 18-point scan runs in about 1.4 seconds, in 9 languages.

View Demo

~28 pages

A4 PDF Report

3-5 years

Forward Forecast

~1.4s

Full 5-Year Scan

Languages

Built for subscription astrology apps and astrologer-entrepreneurs

Transits, profections, and Firdaria in one document

Station-aware peaks pulled from the timing engine

A flat transit list reads like a spreadsheet, so users skim it once and never return
Building a multi-year scan by hand means stitching ephemeris loops, retrogrades, and stations yourself
Generic forecasts ignore the natal chart, so every user gets near-identical filler
Profections and Firdaria live in separate tools, so the time-lord context is missing
No sense of when transits actually peak, so retrograde stations get flattened into a date range
Nothing tells a user the single best day to act, so the report has no clear next step

Replace flat transit lists with

Outer-planet life chapters give the report a narrative arc users come back to read
One call runs the full 3-to-5-year scan, with retrogrades and stations already handled
Every window is computed against the user's own natal points, so no two reports match
A Firdaria time-lord overlay and annual profection briefings sit inside the same PDF
Station-aware peaks mark the exact date a transit is strongest, not just a vague span
Best Days to Act pulls personalized dates from the electional engine for each top window

Built for High-Value, Re-Engaging Content

Premium depth, single-call simplicity

~28 pages

PDF Length

3-5 years

Forecast Range

~1.4s

Full Scan Time

Natal Points Scanned

Languages

Forecast Layers

One Call, A Full Forecast Document

Every layer of a multi-year reading in a single PDF

Outer-Planet Life Chapters

Sign ingresses of Jupiter through Pluto divide the years into a readable narrative arc

Station-Aware Transit Windows

Activation windows to every natal point, each marked with the exact date the transit peaks

Annual Profection Briefings

Birthday-to-birthday profection years naming the house in focus and its ruling planet

Firdaria Time-Lord Overlay

Major and minor Firdaria periods mapped across the same forecast span

Monthly Intensity Calendar

A heat-map scoring every month by how much activation it carries

Convergence Detection

Flags the months where transit, profection, and Firdaria layers point the same way

Life-Area Decision Matrix

A quarter-by-area grid marking favorable and challenging windows per life area

Best Days to Act

Optimal personalized dates from the electional engine inside the top windows

Year-Stacked Gantt Chart

All transit windows on one timeline so overlap is visible at a glance

Nine-Language Output

The full report in en, ru, de, fr, es, it, pt, zh, and tr from one endpoint

One-Call PDF

A finished ~28-page A4 document, no layout work needed on your side

Fast Memoized Scan

A full 5-year, 18-point scan in about 1.4 seconds

Multi-Year Transit Roadmap API Documentation

A 3-to-5-year forecast PDF in one call: transits, profections, Firdaria, and best days

The Multi-Year Transit Roadmap API turns a birth chart into a ~28-page A4 PDF that forecasts the next three to five years. One POST to /api/v3/pdf/multi-year-roadmap-report runs a full outer-planet scan against the user's natal chart and returns a finished document, not raw JSON you have to lay out yourself. The report opens with life chapters set by outer-planet sign ingresses, then walks through transit activation windows to every natal point, with station-aware peaks that mark the exact date each transit is strongest. On top of the transit layer it adds annual profection briefings running birthday to birthday, a Firdaria time-lord overlay, a monthly intensity calendar, convergence detection where transit and time-lord layers stack, a life-area decision matrix, and Best Days to Act pulled from the electional engine. The full 5-year, 18-point scan runs in about 1.4 seconds and the report is available in 9 languages. If you sell a year-ahead premium tier or run a subscription astrology app, this is the kind of content that justifies the renewal: each new year re-anchors the forecast and gives users a reason to come back.

What is the Multi-Year Transit Roadmap?

The Multi-Year Transit Roadmap is a premium PDF forecast for the next three to five years, built from one API call.

You send a subject (name and birth data) plus a years value between 3 and 5, a language, and a tradition, and the endpoint returns a ~28-page A4 portrait PDF.

Behind the scenes it calls the timing engine: stations for retrograde peaks, transits for activation windows, and convergence for where layers stack.

The document is structured like a book, not a data dump.

Life chapters frame the years, transit windows fill in the detail, and the closing sections turn all of it into specific dates a user can act on.

Because everything is computed against the user's own natal chart, the output is personal, which is what makes it worth charging for.

The whole scan, across 18 natal points and five years, completes in about 1.4 seconds thanks to memoization.

One call returns a finished ~28-page personalized forecast PDF, not raw data

1 min read

How does the roadmap structure three to five years?

The report uses outer-planet sign ingresses to break the forecast into life chapters.

When Jupiter, Saturn, Uranus, Neptune, or Pluto changes sign, the tone of a stretch of time shifts, and the report uses those shifts as chapter dividers so the years read as a story rather than a flat timeline.

Inside each chapter, the API lays out the full outer-planet transit activation windows to every natal point, with each window marked by a station-aware peak that pins the exact date the transit is strongest instead of giving a vague multi-month span.

A year-stacked Gantt chart shows all of those windows at once, so a user can see overlap at a glance.

The years value (3 to 5) controls how far forward the scan runs, which lets you offer a shorter forecast on a lower tier and the full five years on a premium plan.

Outer-planet ingresses set the chapters; station-aware peaks pin each window

1 min read

How do profections and Firdaria fit in?

Transits alone tell you what is hitting the chart, but not which part of life is in focus that year.

The roadmap adds two time-lord layers to answer that.

Annual profection briefings run birthday to birthday and name the profected house and its lord, so each year of the forecast has a clear theme.

The Firdaria overlay assigns the major and minor planetary periods across the same span, giving a second, slower-moving time-lord track.

The report then runs convergence detection: it flags the months where a transit window, a profection lord, and a Firdaria period all point at the same area.

Those stacked months are the ones worth highlighting to a user, because that is where the chart is saying the same thing three different ways.

Pulling these three systems into one document is exactly the work most apps never get around to building.

Profections plus Firdaria add the time-lord context flat transit lists miss

1 min read

What is the monthly intensity calendar and decision matrix?

Two visual sections turn the forecast into something a non-astrologer can use.

The monthly intensity heat-map scores each month across the forecast by how much activation it carries, so a user can see at a glance which stretches are busy and which are quiet.

The life-area decision matrix is a quarter-by-area grid: for each life area, it marks which quarters look favorable and which look challenging, so someone planning a launch, a move, or a big purchase can read the chart by the area they care about rather than by planet.

Both sections sit on top of the same transit and time-lord math, so the calendar and the matrix never disagree with the detailed windows earlier in the report.

This is the part that makes the document feel like advice instead of an ephemeris printout.

A heat-map and a quarter-by-area grid make the forecast readable by anyone

1 min read

How does Best Days to Act work?

A forecast that ends with 'this quarter looks good' leaves the user with no next step.

The roadmap closes that gap.

For the top favorable windows in the report, it calls the electional engine to find the specific optimal dates inside each window, then lists them in a Best Days table.

So instead of pointing at a vague favorable stretch, the report names the actual days that score best for acting.

This is the section users screenshot and the one that gives the whole document a payoff.

It is also a natural re-engagement hook: as time passes and new windows open, the best days shift, which is a reason to regenerate the report and a reason for a user to keep their subscription active across years.

Electional best days turn favorable windows into specific dates users can act on

1 min read

Why is this good for retention and recurring revenue?

A multi-year roadmap is high-perceived-value content, which makes it a strong anchor for an annual subscription or a year-ahead premium upsell.

Unlike a daily horoscope a user reads and forgets, a 5-year forecast is something they keep, revisit, and check against real events.

Each new year re-anchors the forecast: a fresh birthday triggers a new profection year, transit windows move, and the best days change, so regenerating the report gives a lapsed user a concrete reason to return.

The PDF is also shareable, which helps word-of-mouth.

Because the whole thing comes from one ~1.4s call in 9 languages, you can offer it as a paid export without building a forecasting engine in-house.

For an indie SaaS or an astrologer productizing annual readings, that is the difference between a feature you maintain and one you simply call.

High-value, re-anchoring content that justifies annual renewals and upsells

1 min read

Use Cases

Subscription Astrology Apps

Offer a year-ahead premium tier that re-anchors every birthday and keeps users renewing

Astrologer-Entrepreneurs

Productize an annual reading as a polished ~28-page PDF you generate in one call

Indie SaaS Builders

Add a paid forecast export without building a multi-year scan engine yourself

Coaching & Planning Tools

Give clients a decision matrix and best days for launches, moves, and big choices

Premium Report Upsells

Sell a multi-year forecast as a one-off upgrade on top of a free natal reading

Localized Forecast Products

Ship the same report in 9 languages from one endpoint for global audiences

Technical Specifications

Endpoint	POST /api/v3/pdf/multi-year-roadmap-report
Response Type	application/pdf
PDF Length	~28 pages, A4 portrait
Forecast Range	3 to 5 years (years field)
Full Scan Time	~1.4s (5 years, 18 points)
Natal Points Scanned	18
Languages	en, ru, de, fr, es, it, pt, zh, tr
Forecast Layers	Transits, profections, Firdaria
Transit Peaks	Station-aware (retrograde-correct)
Convergence Detection	Where transit + time-lord layers stack
Decision Matrix	Quarter by life-area grid
Best Days	Pulled from electional engine
Visuals	Gantt chart, intensity heat-map, tables
Calc Endpoints Behind It	/timing/stations, /timing/transits, /timing/convergence
Language Field	Top-level language parameter
Tradition Field	universal default
Input Formats	City + country code, plus date and time
Memoization	Scan cached for fast repeat calls

Multi-Year Transit Roadmap Comparison

Feature	Astrology API	Others
Forecast Range	3-5 years in one call	1 year or single transit
Output	Finished ~28-page PDF	Raw JSON or flat list
Scan Time	~1.4s full 5-year scan	Hand-built loops, minutes
Transit Peaks	Station-aware	Flat date ranges
Profections		×
Firdaria Overlay		×
Convergence Detection		×
Decision Matrix	Quarter by life-area	Not provided
Best Days to Act	Electional dates	None
Languages	9	1-2
Personalization	Per natal chart	Generic templates
Price	$11/month	$49-99/month
Free Tier	50 requests	No free tier

Related Predictive APIs

Transit API

Real-time and forward transit calculations

Predictive API

Forecasting across multiple timing systems

Profections API

Annual profection years and lords

Firdaria API

Time-lord periods and sub-periods

Electional API

Best days and optimal timing

PDF Report API

Finished PDF reports from one call

Solar Return API

Year-ahead solar return charts

References & Standards

Swiss Ephemeris (DE431-based) — astronomical calculations source
NASA JPL Planetary Ephemerides — underlying ephemeris dataset
International Astronomical Union (IAU) — body designation and nomenclature standards
IANA Time Zone Database — timezone & DST resolution

Simple, Transparent Pricing

Start free, scale as you grow. No hidden fees, no surprises.

Always Free

Start Free

Perfect for learning, testing, and small personal projects

50 API calls/month

Basic natal charts

5 house systems

Community support

Pro

$11/month

For small apps and personal projects

All basic endpoints
12 house systems
Email support

Best Value

Pro Plus

$21/month

For growing apps and medium traffic

All enhanced endpoints
18 house systems
AI interpretations
Priority email support

Ultra

$37/month

For professional astrology applications

Credit math ↓

All premium endpoints
23 house systems
Advanced AI interpretations
Priority support

High Volume Plans

For enterprise-scale applications

Business

$99/month

For high-volume applications

Credit math ↓

ALL endpoints
White-label ready
Custom AI fine-tuning
Phone support

UNLIMITED

Enterprise

$399+per month

Unlimited requests with dedicated infrastructure

Dedicated server infrastructure
Sub-300ms guaranteed
24/7 dedicated support
99.99% uptime SLA

All plans include comprehensive documentation and SDKs

Questions? Talk to our team

Multi-Year Transit Roadmap FAQ

The forecast, the layers, and the report answered

Complete Your Predictive Stack

The Multi-Year Transit Roadmap pairs naturally with the rest of our forecasting toolkit. Add

transit calculations predictive forecasting annual profections firdaria periods electional best days pdf reports solar returns

Ship a Year-Ahead Product That

Give users a ~28-page forecast they keep and revisit: transit windows, profections, Firdaria, and best days, generated in one call across 9 languages.

Start Free Now Compare Features

30 day money back

Free integration support

No setup fees

A 5-Year Forecast PDF That Earns Annual Subscriptions

Year-Ahead Reports Are Hard to Build and Easy to Churn

Astrology API Multi-Year Transit Roadmap

Built for High-Value, Re-Engaging Content

One Call, A Full Forecast Document

Outer-Planet Life Chapters

Station-Aware Transit Windows

Annual Profection Briefings

Firdaria Time-Lord Overlay

Monthly Intensity Calendar

Convergence Detection

Life-Area Decision Matrix

Best Days to Act

Year-Stacked Gantt Chart

Nine-Language Output

One-Call PDF

Fast Memoized Scan

Multi-Year Transit Roadmap API Documentation

What is the Multi-Year Transit Roadmap?

How does the roadmap structure three to five years?

How do profections and Firdaria fit in?

What is the monthly intensity calendar and decision matrix?

How does Best Days to Act work?

Why is this good for retention and recurring revenue?

Use Cases

Subscription Astrology Apps

Astrologer-Entrepreneurs

Indie SaaS Builders

Coaching & Planning Tools

Premium Report Upsells

Localized Forecast Products

Technical Specifications

Multi-Year Transit Roadmap Comparison

Related Predictive APIs

Transit API

Predictive API

Profections API

Firdaria API

Electional API

PDF Report API

Solar Return API

References & Standards

Simple, Transparent Pricing

Always Free

Pro

Pro Plus

Ultra

High Volume Plans

Business

Enterprise

Multi-Year Transit Roadmap FAQ

What is the Multi-Year Transit Roadmap API?

How many years does it forecast?

What does the response look like?

What is a station-aware transit peak?

How do the life chapters work?

What are the annual profection briefings?

What is the Firdaria overlay?

What is convergence detection?

What is the life-area decision matrix?

How does Best Days to Act work?

How fast is the full scan?

What languages are supported?

What does the request body look like?

Which endpoints run behind the report?

Why is this good for subscription retention?

Who is this API for?

How much does the Multi-Year Transit Roadmap cost?

Is there a free tier?

What visuals are in the PDF?

How do I integrate it into my app?

Complete Your Predictive Stack

Ship a Year-Ahead Product That

Year-Ahead Reports Are Hard to Build and Easy to Churn

Astrology API Multi-Year Transit Roadmap

Built for High-Value, Re-Engaging Content

One Call, A Full Forecast Document

Outer-Planet Life Chapters

Station-Aware Transit Windows

Annual Profection Briefings