Authentication
All API requests require authentication using an API key. Include your key in the Authorization header.
Authorization: Bearer at_live_your_api_key_here
Get your API key from the Dashboard. Pay with $TIAN on Base to activate a subscription plan.
Base URL & Request Format
Base URL
https://api.asktian.comAll endpoints use tRPC over HTTP. For GET queries, pass input as a URL-encoded JSON string:
GET /trpc/{procedure}?input={"json":{...params}}For mutations (POST):
POST /trpc/{procedure}
Content-Type: application/json
{"json":{...params}}Divination Lot Systems
Available system slugs for the divination.draw and divination.list endpoints:
| Slug | System Name | Total Lots |
|---|---|---|
leiyushi | 雷雨師一百籤 | 101 |
jiaziqian | 六十甲子籤 | 64 |
guanyin | 觀音一百籤 | 100 |
baosheng | 保生大帝六十籤 | 61 |
penghu | 澎湖天后宮一百籤 | 100 |
asakusa | 淺草觀音寺一百籤 | 101 |
guanyin28 | 觀音二八籤 | 28 |
guanyin24 | 觀音二四籤 | 24 |
zhusheng | 註生娘娘三十籤 | 30 |
jinqian | 金錢卦三十二籤 | 32 |
Divination Lots
3 endpoints/trpc/divination.systemsList all available divination lot systems
Example Request
curl https://api.asktian.com/trpc/divination.systems
Example Response
{"result":{"data":{"json":[{"id":1,"name":"觀音一百籤","slug":"guanyin","totalLots":100}]}}}/trpc/divination.drawDraw a random or specific divination lot
Parameters
systemSlugstringe.g. guanyin, leiyushilotNumberstring?Optional specific lot numberExample Request
curl "https://api.asktian.com/trpc/divination.draw?input=%7B%22json%22%3A%7B%22systemSlug%22%3A%22guanyin%22%7D%7D"
Example Response
{"result":{"data":{"json":{"lotNumber":"42","title":"第四十二籤","fortuneLevel":"good_fortune","poemText":"...","interpretation":"..."}}}}/trpc/divination.listList all lots in a system with optional fortune level filter
Parameters
systemSlugstringSystem identifierfortuneLevelstring?great_fortune | good_fortune | neutral | caution | bad_fortunepagenumberPage number (default: 1)limitnumberItems per page (default: 20, max: 100)Example Request
curl "https://api.asktian.com/trpc/divination.list?input=%7B%22json%22%3A%7B%22systemSlug%22%3A%22guanyin%22%2C%22fortuneLevel%22%3A%22good_fortune%22%7D%7D"
Example Response
{"result":{"data":{"json":{"lots":[...],"total":45,"system":{...}}}}}Qimen Dunjia 奇門遁甲
2 endpoints/trpc/qimen.calculateCalculate a Qimen Dunjia chart for a given date and time
Parameters
yearnumberYear (1900-2100)monthnumberMonth (1-12)daynumberDay (1-31)hournumberHour (0-23)questionstring?Optional question for contextExample Request
curl "https://api.asktian.com/trpc/qimen.calculate?input=%7B%22json%22%3A%7B%22year%22%3A2024%2C%22month%22%3A3%2C%22day%22%3A15%2C%22hour%22%3A10%7D%7D"
Example Response
{"result":{"data":{"json":{"palaces":[...],"rotationNumber":5,"escapeType":"yang","gates":[...],"stars":[...],"deities":[...]}}}}/trpc/qimen.elementsGet reference data for Qimen elements (gates, stars, deities, stems, palaces)
Parameters
elementTypestring?gate | star | deity | stem | palaceExample Request
curl "https://api.asktian.com/trpc/qimen.elements?input=%7B%22json%22%3A%7B%22elementType%22%3A%22gate%22%7D%7D"
Example Response
{"result":{"data":{"json":[{"name":"休門","element":"water","nature":"auspicious","meaning":"..."}]}}}Liuyao 六爻
1 endpoint/trpc/liuyao.calculateGenerate a Liuyao hexagram reading
Parameters
methodstringcoin | time | numbercoinFlipsnumber[]?Array of 6 coin flip results (3=yang, 2=yin)questionstring?Optional questionnumbersnumber[]?Numbers for number methodExample Request
curl "https://api.asktian.com/trpc/liuyao.calculate?input=%7B%22json%22%3A%7B%22method%22%3A%22time%22%7D%7D"
Example Response
{"result":{"data":{"json":{"hexagram":"乾","lines":[...],"changingLines":[...],"resultHexagram":"...","interpretation":"..."}}}}Meihua Yishu 梅花易數
1 endpoint/trpc/meihua.calculateCalculate a Meihua Yishu hexagram from numbers
Parameters
upperNumbernumberUpper trigram numberlowerNumbernumberLower trigram numberchangingLinenumber?Changing line (1-6)questionstring?Optional questionExample Request
curl "https://api.asktian.com/trpc/meihua.calculate?input=%7B%22json%22%3A%7B%22upperNumber%22%3A7%2C%22lowerNumber%22%3A3%7D%7D"
Example Response
{"result":{"data":{"json":{"upperTrigram":"...","lowerTrigram":"...","hexagram":"...","interpretation":"..."}}}}Name Analysis 姓名學
2 endpoints/trpc/nameAnalysis.analyzeAnalyze a Chinese name using numerology and Five Elements
Parameters
surnamestringSurname (姓)givenNamestringGiven name (名)genderstring?male | femaleExample Request
curl "https://api.asktian.com/trpc/nameAnalysis.analyze?input=%7B%22json%22%3A%7B%22surname%22%3A%22%E6%9D%8E%22%2C%22givenName%22%3A%22%E5%BF%97%E6%98%8E%22%7D%7D"
Example Response
{"result":{"data":{"json":{"tianGe":{"number":8,"element":"metal","fortune":"good"},"renGe":{"number":15,"element":"earth"},"totalScore":82,"recommendation":"..."}}}}/trpc/nameAnalysis.numerologyLook up the meaning of a specific numerology number (1-81)
Parameters
numbernumberNumerology number (1-81)Example Request
curl "https://api.asktian.com/trpc/nameAnalysis.numerology?input=%7B%22json%22%3A%7B%22number%22%3A81%7D%7D"
Example Response
{"result":{"data":{"json":{"number":81,"fortune":"great_fortune","meaning":"Supreme achievement"}}}}Compatibility 配對
3 endpoints/trpc/compatibility.zodiacChinese zodiac compatibility analysis
Parameters
animal1stringe.g. rat, ox, tiger, rabbit...animal2stringe.g. rat, ox, tiger, rabbit...Example Request
curl "https://api.asktian.com/trpc/compatibility.zodiac?input=%7B%22json%22%3A%7B%22animal1%22%3A%22rat%22%2C%22animal2%22%3A%22dragon%22%7D%7D"
Example Response
{"result":{"data":{"json":{"score":90,"level":"excellent","description":"...","advice":"..."}}}}/trpc/compatibility.birthdayBirthday-based compatibility analysis
Parameters
date1stringISO date YYYY-MM-DDdate2stringISO date YYYY-MM-DDExample Request
curl "https://api.asktian.com/trpc/compatibility.birthday?input=%7B%22json%22%3A%7B%22date1%22%3A%221990-01-15%22%2C%22date2%22%3A%221992-06-20%22%7D%7D"
Example Response
{"result":{"data":{"json":{"score":75,"element1":"water","element2":"wood","harmony":"generating","description":"..."}}}}/trpc/compatibility.bloodTypeBlood type compatibility analysis
Parameters
type1stringA | B | AB | Otype2stringA | B | AB | OExample Request
curl "https://api.asktian.com/trpc/compatibility.bloodType?input=%7B%22json%22%3A%7B%22type1%22%3A%22A%22%2C%22type2%22%3A%22O%22%7D%7D"
Example Response
{"result":{"data":{"json":{"score":70,"description":"Balanced relationship with mutual respect"}}}}Auspiciousness 吉利
1 endpoint/trpc/auspicious.analyzeNumberAnalyze auspiciousness of a number (phone, license plate, ID, address)
Parameters
numberstringNumber string to analyzecontextstringphone | license_plate | id | address | generalExample Request
curl "https://api.asktian.com/trpc/auspicious.analyzeNumber?input=%7B%22json%22%3A%7B%22number%22%3A%2288888888%22%2C%22context%22%3A%22phone%22%7D%7D"
Example Response
{"result":{"data":{"json":{"overallScore":95,"fortuneLevel":"great_fortune","digitAnalysis":[...],"summary":"..."}}}}Almanac 黃曆
2 endpoints/trpc/almanac.dailyGet daily almanac data including twelve values, deities, and auspicious activities
Parameters
datestringDate in YYYY-MM-DD formatExample Request
curl "https://api.asktian.com/trpc/almanac.daily?input=%7B%22json%22%3A%7B%22date%22%3A%222024-03-15%22%7D%7D"
Example Response
{"result":{"data":{"json":{"date":"2024-03-15","twelveValue":"成","deity":"青龍","overallFortune":"good_fortune","auspiciousActivities":[...],"inauspiciousActivities":[...]}}}}/trpc/almanac.zodiacSignGet Western and Chinese zodiac signs for a birth date
Parameters
birthDatestringBirth date in YYYY-MM-DD formatExample Request
curl "https://api.asktian.com/trpc/almanac.zodiacSign?input=%7B%22json%22%3A%7B%22birthDate%22%3A%221990-05-15%22%7D%7D"
Example Response
{"result":{"data":{"json":{"western":{"sign":"Taurus","element":"earth"},"chinese":{"animal":"horse","element":"metal","year":1990}}}}}Xiao Liu Ren
1 endpoint/trpc/xiaoLiuRen.calculateSix Gods cycle divination — the most widely used folk divination method in Chinese culture
Parameters
monthnumberMonth (1–12)daynumberDay of month (1–31)hournumberHour in 24h format (0–23)aspectstring?general | career | wealth | health | relationship | travel | lostquestionstring?Optional question for contextExample Request
curl "https://api.asktian.com/trpc/xiaoLiuRen.calculate?input=%7B%22json%22%3A%7B%22month%22%3A3%2C%22day%22%3A3%2C%22hour%22%3A10%2C%22aspect%22%3A%22career%22%7D%7D"
Example Response
{"result":{"data":{"json":{"system":"Xiao Liu Ren (小六壬)","result":{"god":"速喜","number":2,"nature":"auspicious","meaning":"..."},"reading":{"aspect":"career","interpretation":"...","advice":"..."},"allAspects":{"general":"...","career":"...","wealth":"..."},"countingPath":{"monthStep":{"god":"大安"},"dayStep":{"god":"速喜"},"hourStep":{"god":"速喜"}}}}}}Da Liu Ren
1 endpoint/trpc/daLiuRen.calculateFour Courses (四課) and Three Transmissions (三傳) — one of the Three Styles of classical Chinese divination
Parameters
yearnumberYear (1900–2100)monthnumberMonth (1–12)daynumberDay of month (1–31)hournumberHour in 24h format (0–23)subjectstring?career | relationship | health | wealth | travel | generalquestionstring?Optional question for contextExample Request
curl "https://api.asktian.com/trpc/daLiuRen.calculate?input=%7B%22json%22%3A%7B%22year%22%3A2026%2C%22month%22%3A3%2C%22day%22%3A3%2C%22hour%22%3A10%2C%22subject%22%3A%22career%22%7D%7D"
Example Response
{"result":{"data":{"json":{"system":"Da Liu Ren (大六壬)","dayPillar":{"stem":"庚","branch":"寅"},"fourCourses":[{"position":"First Course","upper":"子","lower":"寅","meaning":"..."}],"threeTransmissions":{"initial":{"branch":"子","general":{"nameZh":"天后","nameEn":"Heavenly Empress","nature":"auspicious"}},"middle":{"branch":"亥","general":{"nameZh":"天空","nameEn":"Heavenly Void","nature":"neutral"}},"final":{"branch":"戌","general":{"nameZh":"白虎","nameEn":"White Tiger","nature":"inauspicious"}}},"overallAssessment":{"nature":"mixed","summary":"..."},"calculatedAt":"2026-03-03T10:00:00.000Z"}}}}Tai Yi Shen Shu
1 endpoint/trpc/taiYi.calculate72-year Grand Cycle cosmic forecasting — macro-level state, era, and natural event predictions
Parameters
yearnumberYear (1900–2100)monthnumberMonth (1–12)daynumberDay of month (1–31)scopestring?annual | monthly | eraquestionstring?Optional question for contextExample Request
curl "https://api.asktian.com/trpc/taiYi.calculate?input=%7B%22json%22%3A%7B%22year%22%3A2026%2C%22month%22%3A3%2C%22day%22%3A3%2C%22scope%22%3A%22annual%22%7D%7D"
Example Response
{"result":{"data":{"json":{"system":"Tai Yi Shen Shu (太乙神數)","taiYiNumber":9,"rulingGod":{"nameZh":"太乙","nameEn":"Grand Unity","nature":"auspicious"},"cycleInfo":{"cycleNumber":28,"cyclePosition":18,"totalCycleLength":72},"activePalace":{"nameZh":"天門","nameEn":"Heavenly Gate","direction":"NW","element":"metal"},"domainForecasts":{"governance":"...","military":"...","agriculture":"...","commerce":"...","naturalEvents":"..."},"cosmicWeather":{"assessment":"favorable","message":"..."},"disclaimer":"Tai Yi Shen Shu is a macro-level forecasting system...","calculatedAt":"2026-03-03T10:00:00.000Z"}}}}Tarot 塔羅牌
1 endpoint/trpc/tarot.drawDraw a Tarot spread from the 78-card Rider-Waite deck — Major & Minor Arcana with full interpretations
Parameters
spreadstring?single | three_card | celtic_cross (default: single)questionstring?Optional question for context (max 500 chars)seednumber?Optional seed for reproducible drawsExample Request
curl "https://api.asktian.com/trpc/tarot.draw?input=%7B%22json%22%3A%7B%22spread%22%3A%22three_card%22%2C%22question%22%3A%22What+should+I+focus+on%3F%22%7D%7D"
Example Response
{"result":{"data":{"json":{"system":"Tarot","spread":"three_card","cards":[{"position":"Past","card":"The High Priestess","arcana":"major","reversed":false,"interpretation":"Intuition, sacred knowledge, divine feminine..."},{"position":"Present","card":"Three of Wands","arcana":"minor","suit":"Wands","reversed":false,"interpretation":"Growth, collaboration, initial success..."},{"position":"Future","card":"The Star","arcana":"major","reversed":false,"interpretation":"Hope, faith, purpose, renewal..."}],"overallTheme":"...","advice":"..."}}}}Coin Flip Oracle 銅錢占卜
1 endpoint/trpc/coinFlip.flipClassic yes/no oracle with weighted probability and 7 domain-specific interpretations
Parameters
questionstring?Optional question for contextaspectstring?general | career | love | wealth | health | travel | questionflipsnumber?Number of flips 1–9 (default: 1)seednumber?Optional seed for reproducible resultsExample Request
curl "https://api.asktian.com/trpc/coinFlip.flip?input=%7B%22json%22%3A%7B%22aspect%22%3A%22career%22%2C%22flips%22%3A3%7D%7D"
Example Response
{"result":{"data":{"json":{"system":"Coin Flip Oracle","aspect":"career","flips":[{"flip":1,"result":"heads","symbol":"☀"},{"flip":2,"result":"heads","symbol":"☀"},{"flip":3,"result":"tails","symbol":"☽"}],"summary":{"headsCount":2,"tailsCount":1,"majority":"heads","certainty":"moderate"},"interpretation":"A green light for professional decisions...","advice":"Trust the signal. Act with intention."}}}}Runes 盧恩文字
1 endpoint/trpc/runes.castCast Elder Futhark runes — 24 runes with full meanings, elements, and deity associations
Parameters
spreadstring?single | three_rune | five_rune (default: single)questionstring?Optional question for contextseednumber?Optional seed for reproducible castsExample Request
curl "https://api.asktian.com/trpc/runes.cast?input=%7B%22json%22%3A%7B%22spread%22%3A%22three_rune%22%7D%7D"
Example Response
{"result":{"data":{"json":{"system":"Elder Futhark Runes","spread":"three_rune","cast":[{"position":"Past / Situation","rune":"Fehu","letter":"F","meaning":"Cattle, wealth, abundance","element":"Fire","deity":"Freyr","reversed":false,"interpretation":"Wealth, prosperity, new beginnings..."},{"position":"Present / Action","rune":"Ansuz","letter":"A","meaning":"God, mouth, divine breath","reversed":false,"interpretation":"Signals, messages, inspiration..."},{"position":"Future / Outcome","rune":"Sowilo","letter":"S","meaning":"Sun, success, wholeness","reversed":false,"interpretation":"Success, goals achieved, honor..."}],"overallMessage":"...","advice":"..."}}}}Numerology 西方數字學
1 endpoint/trpc/numerology.calculatePythagorean numerology — Life Path, Expression, Soul Urge, Personality, and Birthday numbers from name and birthdate
Parameters
fullNamestringFull name as on birth certificate (required)birthdatestringBirthdate in YYYY-MM-DD format (required)Example Request
curl "https://api.asktian.com/trpc/numerology.calculate?input=%7B%22json%22%3A%7B%22fullName%22%3A%22John+Smith%22%2C%22birthdate%22%3A%221990-06-15%22%7D%7D"
Example Response
{"result":{"data":{"json":{"system":"Pythagorean Numerology","numbers":{"lifePath":{"number":3,"title":"The Creative","traits":["expressive","optimistic","creative","social"],"upright":"Gifted communicator and creative force..."},"expression":{"number":7,"title":"The Seeker"},"soulUrge":{"number":5,"title":"The Adventurer"},"personality":{"number":2,"title":"The Diplomat"},"birthday":{"number":6,"title":"The Nurturer"}},"masterNumbers":[],"summary":"..."}}}}Western Astrology 西洋占星
1 endpoint/trpc/astrology.calculateSun, Moon, and Rising sign analysis with decanates, element profile, modalities, and ruling planets
Parameters
birthdatestringBirthdate in YYYY-MM-DD format (required)birthHournumber?Birth hour 0–23 for Rising sign accuracy (optional)questionstring?Optional question for contextExample Request
curl "https://api.asktian.com/trpc/astrology.calculate?input=%7B%22json%22%3A%7B%22birthdate%22%3A%221990-06-15%22%2C%22birthHour%22%3A14%7D%7D"
Example Response
{"result":{"data":{"json":{"system":"Western Astrology","placements":{"sun":{"sign":"Gemini","symbol":"♊","element":"Air","modality":"Mutable","ruling":"Mercury","decan":2,"traits":["curious","adaptable","witty","communicative"],"description":"Quick-minded, versatile, communicative..."},"moon":{"sign":"Scorpio","symbol":"♏"},"rising":{"sign":"Libra","symbol":"♎"}},"elementProfile":{"dominant":"Air","breakdown":{"Air":2,"Water":1}},"synthesis":"..."}}}}