Forem: Karan Desai

How to Build a Tarot Card Reading Widget in JavaScript

Karan Desai — Mon, 27 Apr 2026 10:36:57 +0000

The problem

A client's wellness blog wanted a "card of the day" tarot widget on the homepage. Embedded, no full-page navigation, click-to-draw. They wanted me to ship it before their Monday newsletter went out. I had a Friday afternoon.

Here is the working widget, in vanilla HTML, CSS, and JS, that ended up on their site.

What I used

DivineAPI for the daily tarot endpoint
Vanilla JavaScript (no framework, drops into any site)
~80 lines of HTML + CSS + JS total
20 minutes of actual work, plus 30 minutes I lost to a stupid bug (more on that)

Step 1: Get your API key

The api_key value (goes in the request body)
An Authorization token (goes in the request header as Bearer {token})

Both are required. The brief I was working from had only the api_key, which is why I lost half an hour debugging 401s. Don't be me.

Step 2: The HTML structure

Minimal markup, semantic enough that you can style it however you want.

<div class="tarot-widget" id="tarot-widget">
  <h2 class="tarot-widget__title">Your Card of the Day</h2>

  <div class="tarot-widget__card" id="tarot-card" hidden>
    <img class="tarot-widget__image" id="tarot-image" alt="" />
    <div class="tarot-widget__meta">
      <h3 class="tarot-widget__name" id="tarot-name"></h3>
      <span class="tarot-widget__orientation" id="tarot-orientation"></span>
    </div>
    <div class="tarot-widget__interpretation" id="tarot-interpretation"></div>
    <div class="tarot-widget__tabs">
      <button data-area="love">Love</button>
      <button data-area="career">Career</button>
      <button data-area="finance">Finance</button>
    </div>
  </div>

  <button class="tarot-widget__draw" id="tarot-draw">Draw a Card</button>
  <p class="tarot-widget__hint" id="tarot-hint">Click the button above to see today's card.</p>
</div>

Single container, image on top, name + orientation, interpretation text that switches between three life areas (love, career, finance) on tab click.

Step 3: The JavaScript

Here's the full widget script. It's a single self-contained block, no dependencies.

const API_URL = 'https://astroapi-5.divineapi.com/api/v2/daily-tarot';
const AUTH_TOKEN = 'YOUR_AUTH_TOKEN';   // from your DivineAPI dashboard
const API_KEY = 'YOUR_API_KEY';

const drawBtn = document.getElementById('tarot-draw');
const card = document.getElementById('tarot-card');
const hint = document.getElementById('tarot-hint');
const image = document.getElementById('tarot-image');
const nameEl = document.getElementById('tarot-name');
const orientationEl = document.getElementById('tarot-orientation');
const interpretationEl = document.getElementById('tarot-interpretation');
const tabs = document.querySelectorAll('.tarot-widget__tabs button');

let currentReading = null;

async function drawCard() {
  drawBtn.disabled = true;
  drawBtn.textContent = 'Drawing...';

  // The endpoint expects multipart/form-data, not JSON.
  // Send via FormData. (yes, i found this out the hard way)
  const form = new FormData();
  form.append('api_key', API_KEY);
  form.append('lan', 'en');           // optional. 25 languages supported

  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${AUTH_TOKEN}`
        // do NOT set Content-Type yourself when using FormData,
        // the browser sets the boundary for you
      },
      body: form
    });

    if (!response.ok) {
      throw new Error(`API returned ${response.status}`);
    }

    const json = await response.json();
    currentReading = json.data;
    renderCard(currentReading);
  } catch (err) {
    hint.textContent = `Could not draw a card: ${err.message}`;
    console.error(err);
  } finally {
    drawBtn.disabled = false;
    drawBtn.textContent = 'Draw Again';
  }
}

function renderCard(data) {
  hint.hidden = true;
  card.hidden = false;

  image.src = data.image;
  image.alt = data.card;
  nameEl.textContent = data.card;
  orientationEl.textContent = data.category;   // "Upright" or "Reverse"
  interpretationEl.textContent = data.love;    // default to love panel
  // mark love tab as active
  tabs.forEach(t => t.classList.toggle('is-active', t.dataset.area === 'love'));
}

tabs.forEach(tab => {
  tab.addEventListener('click', () => {
    if (!currentReading) return;
    const area = tab.dataset.area;
    interpretationEl.textContent = currentReading[area];
    tabs.forEach(t => t.classList.toggle('is-active', t === tab));
  });
});

drawBtn.addEventListener('click', drawCard);

What comes back from the endpoint:

{
  "success": 1,
  "data": {
    "card": "SIX OF WANDS",
    "category": "Reverse",
    "career": "This reversed card solely depicts your failure...",
    "love": "This card depicts that you are not stringy mentally...",
    "finance": "This card reversed depicts a complete failure in your life...",
    "image": "https://divineapi.com/admin/uploads/daily_tarot/14_2.jpg",
    "image2": "https://divineapi.com/admin/uploads/daily_tarot/14.jpg"
  }
}

Three interpretation strings (career, love, finance), a card name, an upright-or-reversed flag, and an image URL hosted on DivineAPI's CDN. Perfect for a single-card widget without any extra asset hosting.

Step 4: The CSS

Just enough to look clean. Drop it in a <style> tag or your stylesheet.

.tarot-widget {
  font-family: system-ui, -apple-system, sans-serif;
  max-width: 360px;
  padding: 1.5rem;
  border-radius: 16px;
  background: linear-gradient(160deg, #1a1530 0%, #2d1b4e 100%);
  color: #f3eefb;
  text-align: center;
  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.25);
}

.tarot-widget__title {
  font-size: 1.1rem;
  margin: 0 0 1rem;
  letter-spacing: 0.05em;
  color: #d4b8ff;
}

.tarot-widget__image {
  width: 140px;
  height: auto;
  border-radius: 8px;
  margin: 0 auto 0.75rem;
  display: block;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
}

.tarot-widget__name {
  font-size: 1.25rem;
  margin: 0;
}

.tarot-widget__orientation {
  display: inline-block;
  margin-top: 0.25rem;
  padding: 2px 10px;
  font-size: 0.75rem;
  background: rgba(255, 255, 255, 0.12);
  border-radius: 999px;
}

.tarot-widget__interpretation {
  margin: 1rem 0;
  font-size: 0.9rem;
  line-height: 1.5;
  text-align: left;
  min-height: 6rem;
}

.tarot-widget__tabs {
  display: flex;
  gap: 0.5rem;
  margin-bottom: 1rem;
}

.tarot-widget__tabs button {
  flex: 1;
  padding: 0.5rem;
  background: transparent;
  color: #f3eefb;
  border: 1px solid rgba(255, 255, 255, 0.2);
  border-radius: 6px;
  cursor: pointer;
  font-size: 0.85rem;
}

.tarot-widget__tabs button.is-active {
  background: rgba(212, 184, 255, 0.15);
  border-color: #d4b8ff;
}

.tarot-widget__draw {
  width: 100%;
  padding: 0.75rem;
  background: #d4b8ff;
  color: #1a1530;
  border: none;
  border-radius: 8px;
  font-weight: 600;
  cursor: pointer;
  font-size: 0.95rem;
}

.tarot-widget__draw:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

That's the whole thing. ~80 lines of code, drops into any HTML page.

The part where I got stuck

Two stupid bugs cost me 30 minutes.

Bug 1: Content-Type: application/json instead of FormData. I tried sending the request with JSON.stringify({api_key: 'YOUR_KEY'}) and Content-Type: application/json because that is what every modern API does. The endpoint returned a 422. I read the error twice, swore mildly, and finally checked the docs. The endpoint expects multipart/form-data, not JSON. Switching to FormData fixed it instantly.

The other catch with FormData: do NOT manually set Content-Type: multipart/form-data on the request. The browser needs to add a boundary string, and if you set the header yourself you'll override that and it breaks. Just pass the FormData object as the body and let the browser handle the headers.

Bug 2: missing Authorization header. The first version of my code only included the api_key in the body. Got 401s every time. The endpoint needs both: api_key in the body AND Authorization: Bearer {token} in the header. The dashboard gives you two separate values. Make sure you're using the right one in each place.

Lesson learned: when an API gives you two different credentials, it's because both are required. Always.

What I'd do differently

A few things I'd refactor if I were doing this for real production rather than a Friday afternoon ship:

Move the API call to your backend. I have the auth token in the frontend code above for tutorial clarity. In production, never expose that to the client. Proxy through your own backend so the token stays server-side.
Cache the response per-day. The daily tarot card changes once every 24 hours. No reason to hit the API on every page load. Cache server-side, serve the same response to every user that day.
Add a loading skeleton. The "Drawing..." text is functional but a card-shaped shimmer would feel nicer.
Internationalise the tab labels. I hardcoded "Love", "Career", "Finance" in English. The API supports 25 languages via the lan parameter; the UI should follow.

Wrapping up

That is a self-contained tarot card widget in vanilla JavaScript, 20 minutes of work once you know which endpoints to hit and which content type to send.

Worth knowing: DivineAPI ships 27 different tarot reading endpoints beyond just daily tarot, including yes/no, love triangle, past-present-future, ex-flame reading, fortune cookie, Egyptian prediction, and more. Same auth pattern, same FormData approach, different response shapes. So once you have the daily tarot working, the rest are quick to add as additional widgets.

If you don't want to write any code at all, they also ship pre-built tarot widgets at divineapi.com/widgets/tarot that you can embed directly. Useful if your client just wants the feature live without dev time.

Full docs at developers.divineapi.com, with the live "Run In Postman" button on every endpoint page so you can poke at the request and response before writing any code.

If you ship something with this, drop a comment. Always curious to see what people build.

Build a Daily Horoscope Feature in Python in 10 Minutes (with DivineAPI)

Karan Desai — Sat, 25 Apr 2026 08:49:49 +0000

The problem

A client wanted daily horoscopes on their wellness app. All 12 signs, refreshed daily, English first with Hindi coming in phase two. The deadline was end of week. I did not want to spend three days reading documentation for an API I had never used.

Here is the stack I ended up with, and the working Python you can drop into a project today.

What I used

DivineAPI for the horoscope endpoint
Python 3.11
The requests library (pip install requests)
About 10 minutes of actual work

Step 1: Get your API key

Sign up at divineapi.com, 14-day free trial, you will need a credit card to register. Once you are in the dashboard, grab your API key. Two things they hand you that you will need:

The api_key value (goes in the request body)
An Authorization token (goes in the header as Bearer {token})

Yes, two separate auth bits. I did not catch this on first read and spent ten minutes wondering why I was getting 401s. More on that below.

Step 2: Your first call

Here is the smallest working request for the daily horoscope endpoint:

import requests

url = "https://astroapi-5.divineapi.com/api/v5/daily-horoscope"

headers = {
    "Authorization": "Bearer YOUR_AUTH_TOKEN"
}

payload = {
    "api_key": "YOUR_API_KEY",
    "sign": "leo",
    "h_day": "today",        # also accepts "yesterday" or "tomorrow"
    "tzone": 5.5              # IST. timezone offset as a float, not a string
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

# the prediction is split into 5 life areas + a "luck" array
print(data["data"]["prediction"]["personal"])

That is it. One POST, one JSON response, daily horoscope for Leo.

A few non-obvious bits the docs are right about but easy to miss:

The endpoint is on astroapi-5.divineapi.com, not the apex divineapi.com. They run different astro services on numbered subdomains.
The day parameter is named h_day, not day. I assumed day and got a 422.
tzone is a Float, 5.5 for IST. Not a string. Not "Asia/Kolkata". Not 5. I learned this the hard way (see "the part where I got stuck").
For non-English you swap the host to astroapi-5-translator.divineapi.com and add a lan field. They support 25 languages including Indonesian and Greek (the language list got expanded in April 2026).

What comes back

Here is the actual response shape, trimmed for readability:

{
  "success": 1,
  "data": {
    "sign": "Leo",
    "date": "2026-04-23",
    "prediction": {
      "personal": "Your personal life is full of vibrant energy today...",
      "health": "Pay attention to physical wellness today, Leo...",
      "profession": "Today, you may find yourself inspired at work, Leo...",
      "emotions": "Emotionally, you may feel heightened sensitivity, Leo...",
      "travel": "Adventure calls today, Leo! Whether it's a spontaneous day trip...",
      "luck": [
        "Colors of the day : Gold, Orange",
        "Lucky Numbers of the day : 4, 9, 13",
        "Lucky Alphabets you will be in sync with : L, S",
        "Cosmic Tip : Beware of impulsive actions; stay grounded and focused.",
        "Tips for Singles : Express your interests confidently...",
        "Tips for Couples : Share your dreams; strengthen your bond..."
      ]
    },
    "special": {
      "lucky_color_codes": ["#FFD700", "#FFA500"],
      "horoscope_percentage": {
        "personal": 85, "health": 75, "profession": 80, "emotions": 78
      }
    }
  }
}

Two things worth noticing. The prediction is broken into five life areas (personal, health, profession, emotions, travel) plus a luck array of one-liners. So you can render the full daily horoscope, or just the personal text, or just the lucky numbers as a widget. Useful flexibility. Second, special.lucky_color_codes gives you actual hex codes, which means you can theme the daily card with the lucky colour without writing a sign-to-colour map yourself.

Average response times in my testing came back around 74ms over a few hundred requests, which tracks with their published "from 72ms" claim. Fast enough that you do not need a loading state for a single sign.

Step 3: All 12 signs in one loop

For a daily-refresh job that fills a database or warms a cache, you want every sign in one go. Wrap the call in a function and loop:

import requests

URL = "https://astroapi-5.divineapi.com/api/v5/daily-horoscope"
HEADERS = {"Authorization": "Bearer YOUR_AUTH_TOKEN"}
API_KEY = "YOUR_API_KEY"

SIGNS = [
    "aries", "taurus", "gemini", "cancer", "leo", "virgo",
    "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces"
]

def fetch_daily(sign):
    payload = {
        "api_key": API_KEY,
        "sign": sign,
        "h_day": "today",
        "tzone": 5.5
    }
    r = requests.post(URL, headers=HEADERS, json=payload, timeout=10)
    r.raise_for_status()
    return r.json()["data"]

results = {sign: fetch_daily(sign) for sign in SIGNS}

# now `results["leo"]["prediction"]["personal"]` etc.
print(f"Fetched {len(results)} sign predictions")

Twelve calls, completes in under a second on a decent connection. If you are serving these to users live, cache the response per-sign per-day. The data only changes once every 24 hours. There is no good reason to hit the API on every page load.

Step 4: Add weekly and monthly horoscopes

Same auth, same response shape, different endpoint and one parameter name change:

WEEKLY_URL  = "https://astroapi-5.divineapi.com/api/v5/weekly-horoscope"
MONTHLY_URL = "https://astroapi-5.divineapi.com/api/v5/monthly-horoscope"

def fetch_weekly(sign):
    payload = {
        "api_key": API_KEY,
        "sign": sign,
        "week": "current",     # also "prev" or "next"
        "tzone": 5.5
    }
    r = requests.post(WEEKLY_URL, headers=HEADERS, json=payload, timeout=10)
    return r.json()["data"]

def fetch_monthly(sign):
    payload = {
        "api_key": API_KEY,
        "sign": sign,
        "month": "current",    # also "prev" or "next"
        "tzone": 5.5
    }
    r = requests.post(MONTHLY_URL, headers=HEADERS, json=payload, timeout=10)
    return r.json()["data"]

Worth knowing: DivineAPI ships 6 horoscope endpoints total under the Horoscope and Tarot category. Daily, Weekly, Monthly, Yearly, Chinese Horoscope, and Numerology Horoscope. So if you ever want to add yearly forecasts or Chinese zodiac alongside the Western ones, the same API key covers all of them.

The part where I got stuck

Two stupid bugs cost me about 25 minutes total. Both worth flagging because they will cost you time too if nobody warns you.

Bug 1: "day" vs "h_day". I assumed the parameter would be called day because that is what I would call it. The actual name is h_day. The API responded with a 422 and a perfectly clear error message saying the field was missing. I looked at my code, saw day, and somehow my brain kept reading it as h_day. Three minutes of "but it IS there, what is wrong with this thing". Lesson: when an API says a field is missing and you swear it is there, check the name character by character.

Bug 2: timezone as a string. I sent "tzone": "5.5" because I was building the payload from form input and forgot to cast. The API accepted it, returned a 200, and gave me back a horoscope. Looked fine. Except the date in the response was off by one for a chunk of users, depending on what time of day they hit the endpoint. Took a while to pin down. The API expects tzone as a Float. Send a string and it silently degrades the date calculation. Cast your inputs.

If you are integrating this into a Django or Flask form, do the cast at the serializer layer and write a test for it.

What I'd do differently

Three things, in order of how much pain they would have saved.

Cache aggressively. I should have set up a Redis cache from the start. The horoscope data is per-sign per-day. Twelve API calls per day total, the rest served from cache. Saves the API budget and removes the latency entirely.
Centralise the auth headers. I scattered HEADERS = {...} across three files before I refactored. A small wrapper function or a requests.Session would have been better from day one.
Don't roll your own retry logic. Use tenacity or requests-retry-session for the 5xx case. I wrote a half-baked retry loop, immediately regretted it, and ripped it out for the library.

Wrapping up

That is a working horoscope feature in about 10 minutes of code. You can extend it to weekly, monthly, yearly, Chinese, or numerology horoscopes with the same API key. They have a Postman collection at the docs website which is genuinely useful for poking at the response before you write any code. Full docs at developers.divineapi.com.

DivineAPI has a 14-day free trial if you want to try this yourself. If you ship something with it, drop a comment. Always curious what people end up building.