Use cases

Buyers from East Asia often ask about a home's feng shui before visiting. Store the facing bearing and construction year with each listing and show the Flying Star chart and the Eight Mansions sectors on the detail page — a differentiator competitors rarely offer.

Endpoints: /feng-shui/flying-star, /feng-shui/eight-mansions. Results depend only on the building, so calculate once when the listing is published and store them.

// when a listing is saved (server side)
const [stars, mansions] = await Promise.all([
  api('/feng-shui/flying-star', { facing: listing.facingDegrees, constructionYear: listing.builtYear }),
  api('/feng-shui/eight-mansions', { facing: listing.facingDegrees }),
]);
await db.listings.update(listing.id, { fengShui: { stars, mansions } });

Many customers who follow feng shui check dimensions on the Lu Ban ruler before buying. Show a small badge next to each measurement — and suggest the nearest auspicious size for made-to-measure products.

Endpoint: /feng-shui/lucky-dimension. Compute the badges for your catalogue in a nightly job and cache them.

for (const product of catalogue) {
  for (const [name, cm] of Object.entries(product.dimensions)) {
    const { auspicious, section } = await api('/feng-shui/lucky-dimension', { length: cm, unit: 'cm' });
    product.badges[name] = auspicious ? `Lucky: ${section.meaning}` : null;
  }
}

Add a playful "zodiac match" to profiles. Users already enter their birth date; convert it to an animal once and compare animals at match time — the score is a lookup, so it can be cached for all 144 combinations.

Endpoints: /zodiac/year once per user, then /compatibility/love?animal1=…&animal2=….

const { animal } = await api('/zodiac/year', { date: user.birthDate });
const match = await api('/compatibility/love', { animal1: animal, animal2: other.animal });
// → { score: 3, maxScore: 4, rating: "good" }

Traditional date selection avoids days whose animal clashes with the year animal of the people involved. Mark such days in your calendar picker — a feature couples actively look for.

Endpoints: /zodiac/enemy for each person, then /zodiac/day for the candidate dates (the day cycle never changes, so you can pre-compute a whole year).

const clashes = await Promise.all(people.map(
  (p) => api('/zodiac/enemy', { date: p.birthDate }).then((r) => r.enemy)));
const days = await Promise.all(candidates.map((date) => api('/zodiac/day', { date })));
const suitable = days.filter((d) => !clashes.includes(d.animal));

Show today's Chinese date — year, month and day pillars — on your homepage or in a newsletter. Three calls a day, cached until midnight, keep the widget fresh without touching your quota.

Endpoints: /zodiac/year, /zodiac/month (with calendar=solar for the Ba Zi pillars) and /zodiac/day.

Ask for birth date and gender during onboarding and tell users which way to face at their desk and where to point the bed. Combine it with a compass on mobile for a "find your direction" feature.

Endpoint: /feng-shui/kua — one call per user, store the result in the profile.