Concept Guide

Horoscope API guide

Daily, weekly, monthly and yearly horoscopes, zodiac and Chinese sign lookups and 25+ languages: what the Horoscope API returns and how to call it.

DivineAPI

Harsh, Developer, DivineAPI

Published: November 05, 2026 Horoscope

Horoscope API guide

By Harsh, Developer, DivineAPI

DivineAPI's Horoscope API returns sign horoscopes as JSON from four period endpoints, daily, weekly, monthly and yearly, for the 12 zodiac signs, in English from the main host and in 25+ languages from the translator host. This guide is five runnable Node.js scripts, copied as they are, plus the errors to catch. The failures that bite first are all plumbing: the key in the wrong place, numbers sent as numbers instead of strings, an error hiding in the body behind an HTTP 200. Every call below is a POST with multipart/form-data, a Bearer token in the header and an api_key form field, and on the horoscope host you check success in the JSON rather than the status code. The scripts were run on 3 November 2026 and the outputs under them are from that run.

Start with the smallest thing that works, a daily horoscope for one sign. Run with DIVINEAPI_KEY=YOUR_API_KEY DIVINEAPI_TOKEN=YOUR_TOKEN node daily.mjs.

File: daily.mjs

JavaScript
const API = "https://astroapi-5.divineapi.com/api/v5/daily-horoscope";

const now = new Date(); const form = new FormData(); form.append("api_key", process.env.DIVINEAPI_KEY); form.append("sign", "aries"); form.append("h_day", "today"); form.append("day", String(now.getDate())); form.append("month", String(now.getMonth() + 1)); form.append("year", String(now.getFullYear())); form.append("tzone", "5.5"); form.append("lan", "en");

const res = await fetch(API, { method: "POST", headers: { Authorization: Bearer ${process.env.DIVINEAPI_TOKEN} }, body: form, });

const json = await res.json(); if (String(json.success) !== "1") { console.error(success=${json.success}: ${json.msg ?? "unknown error"}); process.exit(1); }

const d = json.data; console.log("sign:", d.sign, "| date:", d.date); for (const [area, text] of Object.entries(d.prediction)) { console.log(${area}: ${[].concat(text).join(" ").slice(0, 70)}…); }

Output of daily.mjs (run 3 Nov 2026):

Text
$ node daily.mjs
sign: Aries | date: 2026-11-03
personal: Balance in personal relationships could be the theme of the day. Expec…
health: Your energy levels are peaking today, making it an ideal time to engag…
profession: Today you may experience a dynamic shift at work, pushing you to lever…
emotions: Your emotions may be heightened today, calling for introspection and e…
travel: Spontaneous travel plans may arise, offering the chance for adventures…
luck: Colors of the day : Sky Blue, Coral Lucky Numbers of the day : 6, 14, …

Two things to watch in that file. FormData and fetch are built into Node 18+, so you do not need form-data or axios, and you must not set a Content-Type header yourself: the runtime adds the multipart boundary. Every value goes in as a string, including the numbers.

One caveat on the date. new Date() reads the calendar of whatever machine runs the script, while tzone is sent separately, so this example lines up only when the runtime's date already matches the timezone you are asking about. A production proxy serving users in other timezones has to resolve the calendar date for the target tzone itself (shift the clock by the offset, then read the UTC fields) before it builds the form.

Which horoscope API fits a mobile app?

DivineAPI fits a mobile app when you want structured horoscope JSON with language chosen per request, and the right shape is one server-side proxy shared by Android and iOS: the proxy holds the key and the token, picks the host from lan, caches one reply per sign, period, language and date, and returns only the fields the screen renders. Never ship the API key or the Bearer token in an app bundle; treat anything inside an APK or IPA as recoverable. There is no Android or iOS SDK and none is needed, because the proxy speaks plain HTTPS and JSON to the app. The full design, with a React Native client, a cache policy and the proxy contract, is on the Horoscope API page.

The proxy contract decides what the app renders, and which endpoint sits behind it depends on the period each screen shows.

Period endpoints take keywords, not dates

Weekly, monthly and yearly horoscope endpoints take selector keywords rather than date ranges or ISO week numbers. All four endpoints want sign lowercase and tzone as a decimal offset.

Endpoint Selector param Allowed values Response field
/api/v5/daily-horoscope h_day today, tomorrow, yesterday prediction (6 areas)
/api/v5/weekly-horoscope week current, prev, next weekly_horoscope
/api/v5/monthly-horoscope month current, prev, next monthly_horoscope
/api/v5/yearly-horoscope year current, prev, next yearly_horoscope

In English, all four go to astroapi-5.divineapi.com; a non-English lan goes to the translator hostname described in the next section. Watch the overload on month: do not reuse the monthly selector on the daily endpoint, because month means a calendar number there, not a keyword.

File: periods.mjs

JavaScript
const HOST = "https://astroapi-5.divineapi.com/api/v5";

async function horoscope(path, fields) { const form = new FormData(); form.append("api_key", process.env.DIVINEAPI_KEY); form.append("tzone", "5.5"); form.append("lan", "en"); for (const [k, v] of Object.entries(fields)) form.append(k, v);

const res = await fetch(${HOST}/${path}, { method: "POST", headers: { Authorization: Bearer ${process.env.DIVINEAPI_TOKEN} }, body: form, }); const json = await res.json(); if (String(json.success) !== "1") throw new Error(${path}: success=${json.success} ${json.msg ?? ""}); return json.data; }

const weekly = await horoscope("weekly-horoscope", { sign: "leo", week: "current" }); console.log("weekly:", weekly.week); console.log(String(weekly.weekly_horoscope).slice(0, 110), "…");

const monthly = await horoscope("monthly-horoscope", { sign: "leo", month: "current" }); console.log("monthly:", monthly.month); console.log(String(monthly.monthly_horoscope).slice(0, 110), "…");

Output of periods.mjs (run 3 Nov 2026):

Text
$ node periods.mjs
weekly: 01 Nov 2026 to 07 Nov 2026
[object Object] …
monthly: November 2026
[object Object] …

That output is the gotcha, and it is mine. weekly_horoscope and monthly_horoscope came back as objects, not strings, so wrapping them in String() printed [object Object]. The selectors worked: week resolved to the current week's date range and month to the current month. The fix is to stop coercing and read the areas out of the object, the same way daily.mjs iterates prediction.

File: periods-fixed.mjs

JavaScript
const HOST = "https://astroapi-5.divineapi.com/api/v5";

async function horoscope(path, fields) { const form = new FormData(); form.append("api_key", process.env.DIVINEAPI_KEY); form.append("tzone", "5.5"); form.append("lan", "en"); for (const [k, v] of Object.entries(fields)) form.append(k, v);

const res = await fetch(${HOST}/${path}, { method: "POST", headers: { Authorization: Bearer ${process.env.DIVINEAPI_TOKEN} }, body: form, }); const json = await res.json(); if (String(json.success) !== "1") throw new Error(${path}: success=${json.success} ${json.msg ?? ""}); return json.data; }

function show(label, block, areas) { console.log(label); for (const area of areas) { console.log( ${area}: ${[].concat(block[area]).join(" ").slice(0, 60)}…); } }

const weekly = await horoscope("weekly-horoscope", { sign: "leo", week: "current" }); show(weekly: ${weekly.week}, weekly.weekly_horoscope, ["personal", "health", "luck"]);

const monthly = await horoscope("monthly-horoscope", { sign: "leo", month: "current" }); show(monthly: ${monthly.month}, monthly.monthly_horoscope, ["personal", "profession", "luck"]); console.log("percent (personal):", monthly.special.horoscope_percentage.personal);

Output of periods-fixed.mjs (run 3 Nov 2026):

Text
$ node periods-fixed.mjs
weekly: 01 Nov 2026 to 07 Nov 2026
  personal: Your private life is set to bloom with positivity this week,…
  health: Your health looks to be on a favorable track this week, with…
  luck: Colors of the week : Gold, Orange Lucky Numbers of the week …
monthly: November 2026
  personal: Your personal life glows under the Moon's supportive aspects…
  profession: Work settles into a steady rhythm, and the Moon's sextile to…
  luck: Colors of the month : Golden Yellow, Royal Blue Lucky Number…
percent (personal): 80

[].concat() covers both shapes, because luck comes back as a list of strings while the other five areas are plain strings. The special block arrives on all four period responses with lucky_color_codes and horoscope_percentage, so log it once per endpoint before you bind it to a progress bar. The text is sign-based and identical for every user of a sign, so one fetch per sign, period and language serves everyone.

All four also accept lan, and that is where the routing stops being obvious.

Which languages does the horoscope API support?

As of November 2026 the Horoscope API answers in 25+ languages through the lan parameter, which defaults to en. Translation runs only on the translator host, astroapi-5-translator.divineapi.com, after you set up a Translator in the DivineAPI dashboard; the main host answers English only. That is a silent fallback, not an error: in the run below, lan=hi sent to the main host came back success=1 with English text. Same paths, same fields, different hostname. lan takes DivineAPI's own codes, not ISO: hi Hindi, but ma Marathi, tm Tamil, tl Telugu, gr Greek, ta Filipino, bah Indonesian. The daily horoscope page in the docs and the support article "Translating APIs into a different language" walk through the setup.

File: hindi.mjs

JavaScript
const PATH = "/api/v5/daily-horoscope";
const STANDARD = "https://astroapi-5.divineapi.com" + PATH;
const TRANSLATOR = "https://astroapi-5-translator.divineapi.com" + PATH;

function build(lan) { const now = new Date(); const f = new FormData(); f.append("api_key", process.env.DIVINEAPI_KEY); f.append("sign", "aries"); f.append("h_day", "today"); f.append("day", String(now.getDate())); f.append("month", String(now.getMonth() + 1)); f.append("year", String(now.getFullYear())); f.append("tzone", "5.5"); f.append("lan", lan); return f; }

async function post(url, lan) { const res = await fetch(url, { method: "POST", headers: { Authorization: Bearer ${process.env.DIVINEAPI_TOKEN} }, body: build(lan), signal: AbortSignal.timeout(60_000), }); return res.json(); }

const wrong = await post(STANDARD, "hi"); console.log(standard host: success=${wrong.success} | sign: ${wrong.data?.sign ?? ""} | msg: ${wrong.msg ?? ""}); console.log("personal:", [].concat(wrong.data?.prediction?.personal ?? "").join(" ").slice(0, 60), "…");

const hi = await post(TRANSLATOR, "hi"); if (String(hi.success) !== "1") { console.error(translator host: success=${hi.success}: ${hi.msg ?? ""}); process.exit(1); } console.log("translator host: success=1 | sign:", hi.data.sign, "| date:", hi.data.date); console.log("personal:", [].concat(hi.data.prediction.personal).join(" ").slice(0, 60), "…"); console.log("health:", [].concat(hi.data.prediction.health).join(" ").slice(0, 60), "…");

Output of hindi.mjs (run 3 Nov 2026):

Text
$ node hindi.mjs
standard host: success=1 | sign: Aries | msg:
personal: Balance in personal relationships could be the theme of the  …
translator host: success=1 | sign: मेष | date: 2026-11-03
personal: आज का मुख्य विषय व्यक्तिगत संबंधों में संतुलन हो सकता है। पु …
health: आज आपकी ऊर्जा चरम पर है, इसलिए शारीरिक गतिविधि करने का यह आद …

The first two lines are the trap: the main host accepted lan=hi, answered success=1, and sent English. Nothing in the reply says the language was ignored, so a check on success alone passes and Hindi users get English text. Make lan a variable from day one and pick the host from it. One const host = lan === "en" ? STANDARD : TRANSLATOR line, plus a test that asserts the sign field comes back in the requested language, saves an afternoon of debugging with a perfectly valid key. A translated reply can take 25 to 35 seconds, which is why the script sets a 60-second timeout; cache the result. The rule follows the host, not the API version: the Chinese horoscope (v3) and the tarot readings (v2 and v3) sit on astroapi-5 beside the v5 horoscopes, and every one of them needs the translator hostname for a non-English lan. The Hindi daily call is my worked example; I did not run all 25+ codes, so check the language table for the endpoint you call.

Horoscope endpoints take a sign and give you text; getting the sign itself out of a birth date is a different family of calls.

Which zodiac sign API should app developers use for a birth date?

Call a chart endpoint and read the Sun's sign from it: /western-api/v1/planetary-positions for a tropical sign or /indian-api/v2/planetary-positions for a sidereal one. The OpenAPI spec lists no standalone date-only zodiac-sign endpoint. Both are standard birth endpoints on their own hosts (astroapi-4 for Western, astroapi-3 for Vedic) and take the 13 birth fields: full name, day, month, year, hour, min, sec, gender, lowercase place, lat, lon and tzone. sec is required even when unknown; send "0". The Western reply is a list, so find the entry whose name is Sun; the Vedic reply holds the list under data.planets, and the same lookup works.

If your sign-up form collects only a date, you can still get a sun sign today: pin hour to 12 with min and sec at 0 and use a default location, which is what the third call below does. That answer holds except for births on the day the Sun changes sign, where the real time and place decide it. Skip the hard-coded date-range table you see in every tutorial for the same reason: the Sun's ingress shifts from year to year, so the table is wrong for anyone born within a day of a boundary. Compute it, and collect birth time and place when you can.

File: sunsign.mjs

JavaScript
const AUTH = { Authorization: Bearer ${process.env.DIVINEAPI_TOKEN} };
const WESTERN = "https://astroapi-4.divineapi.com/western-api/v1/planetary-positions";
const VEDIC = "https://astroapi-3.divineapi.com/indian-api/v2/planetary-positions";

const birth = { full_name: "Test User", day: "24", month: "05", year: "1990", hour: "14", min: "30", sec: "0", gender: "male", place: "new delhi", // lowercase, always lat: "28.6139", lon: "77.2090", tzone: "5.5", // decimal offset, not "+5:30" lan: "en", };

async function call(url, extra = {}) { const form = new FormData(); form.append("api_key", process.env.DIVINEAPI_KEY); for (const [k, v] of Object.entries({ ...birth, ...extra })) form.append(k, v);

const res = await fetch(url, { method: "POST", headers: AUTH, body: form }); const json = await res.json(); if (String(json.success) !== "1") throw new Error(${url}: success=${json.success} ${json.msg ?? ""}); return json.data; }

const western = await call(WESTERN, { house_system: "P" }); const sun = western.find((p) => p.name === "Sun"); console.log("tropical Sun:", sun.sign, "| degree:", sun.full_degree, "| house:", sun.house);

const vedic = await call(VEDIC); const vSun = vedic.planets.find((p) => p.name === "Sun"); console.log("sidereal Sun:", vSun.sign, "|", vSun.nakshatra, "pada", vSun.nakshatra_pada, "| house:", vSun.house);

// Date only: pin the time to noon and keep a default place. const dateOnly = await call(WESTERN, { hour: "12", min: "0", sec: "0", house_system: "P" }); const noonSun = dateOnly.find((p) => p.name === "Sun"); console.log("date-only Sun:", noonSun.sign, "| degree:", noonSun.full_degree);

Output of sunsign.mjs (run 3 Nov 2026):

Text
$ node sunsign.mjs
tropical Sun: Gemini | degree: 62.9408876 | house: 9
sidereal Sun: Taurus | Krittika pada 4 | house: 9
date-only Sun: Gemini | degree: 62.8407369

Same birth data, two different answers: tropical Gemini and sidereal Taurus, because the sidereal zodiac sits about 24 degrees behind the tropical one under the Lahiri ayanamsa, which is fixed on the Vedic endpoints. Decide tropical or sidereal once, at product level, and label it in the UI; a Western app that quietly serves sidereal sun signs gets support tickets from users who know their sign. Do not carry a Western house_system onto a Vedic call either; the Vedic endpoints do not take it.

Cache the result against the complete normalised birth inputs plus the system you chose. Birth date alone is an unsafe key: two users born on the same date at different times or places can sit on opposite sides of an ingress.

Which API gives the Chinese zodiac animal and element for a date of birth?

As of November 2026, DivineAPI's Chinese horoscope endpoint takes the animal as its input and the OpenAPI spec lists no endpoint that converts a date of birth into a Chinese animal and element, so that lookup belongs in your code. /api/v3/chinese-horoscope on astroapi-5 takes a Chinese sign such as TIGER plus h_day and tzone, all required, and returns the horoscope text for that animal. The conversion itself has one trap: the Chinese year starts at the lunar new year, between 21 January and 20 February, not on 1 January, so a January or early-February birth needs the new-year date for that year before you pick the animal. Compute the animal and element once from the date of birth, store them with the user, and send the animal to the endpoint. The Horoscope API page lists the endpoint family.

What broke while I wrote these scripts

Three snags, plus one guard I would add anyway.

The horoscope host requires body-level success checks, because it returns HTTP 200 for a bad key, a missing param and a typo in the sign alike. The failure lives in the body as success=2 for a validation error and success=3 for an auth error, with the reason in msg; res.ok is true the entire time. That is why every script above checks String(json.success) !== "1" before touching json.data and logs msg on every non-1 reply. The message is the fastest debugging you will get here. Which hosts return real 4xx statuses with an error body instead is on the API docs; if you use both kinds, write two error handlers.

Second, place has to be lowercase. "New Delhi" can be rejected; "new delhi" works. Normalise with .toLowerCase().trim() on the way in.

Third, tzone is a decimal UTC offset and nothing else. IST is 5.5, not "+5:30" and not "Asia/Kolkata". It is not adjusted for DST, so for a summer birth in a DST region you send the offset that was in force at that moment, not the current one.

The guard: if res.json() ever throws SyntaxError: Unexpected token '<', stop trusting the parser and look at the response itself. Read res.status and res.headers.get("content-type"), then print the first 200 characters of await res.text(). An HTML body only tells you that what came back was not JSON; where it came from is still yours to find out. Print it before you guess.

With requests and error handling settled, the last production check is the set of platform features that do not exist, because those shape your scheduling and backfill code.

What the API will not do

No webhooks. No bulk or batch endpoint either, so a backfill for 12 signs is 12 requests in a loop; add your own concurrency limit and retry. There is no published per-second rate limit, which means no safe burst rate to quote here. Keep the concurrency setting configurable and watch what the API returns before you turn it up. Each call counts against the Horoscope plan's monthly quota; the quotas and the overage line are in the pricing page.

FAQ

Is there a Chinese zodiac endpoint? Yes, /api/v3/chinese-horoscope on astroapi-5, which takes a Chinese sign like TIGER plus h_day and tzone. It does not convert a birth date into an animal, and the OpenAPI spec lists no endpoint that does, so resolve the date to a sign in your application first (see the Chinese zodiac section above).

Can I get a horoscope for a numerology number instead of a sign? Yes. /api/v2/numerology-horoscope takes a number (for example 01) plus the day, month and year fields and tzone, on the same host as the sign-based endpoints.

Do I need the birth time for a daily horoscope? No. None of the period endpoints need birth data. Daily needs sign, h_day, tzone plus the calendar date; birth time matters for chart endpoints only.

Is the horoscope personalised to the user? No. Horoscopes are sign-based and identical for every user of a sign in a given language; that is what makes them cacheable. Per-user answers from a natal chart are the AI Astrologer's job (POST /chat).

Related: Horoscope API · Vedic astrology API · Western astrology API

Next thing I would build on this: copy periods-fixed.mjs, point it at yearly-horoscope with year: "current", and check the field names before you wire the screen. Plans are at http://divineapi.com/pricing , and the 14-day free trial (credit card required to activate the trial) starts at http://divineapi.com/start-trial .

Ready to integrate?

Start your free 14-day trial and get API access in under 2 minutes.