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.com

All 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:

SlugSystem NameTotal 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
GET/trpc/divination.systems

List 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}]}}}
GET/trpc/divination.draw

Draw a random or specific divination lot

Parameters

systemSlugstringe.g. guanyin, leiyushi
lotNumberstring?Optional specific lot number

Example 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":"..."}}}}
GET/trpc/divination.list

List all lots in a system with optional fortune level filter

Parameters

systemSlugstringSystem identifier
fortuneLevelstring?great_fortune | good_fortune | neutral | caution | bad_fortune
pagenumberPage 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
GET/trpc/qimen.calculate

Calculate 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 context

Example 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":[...]}}}}
GET/trpc/qimen.elements

Get reference data for Qimen elements (gates, stars, deities, stems, palaces)

Parameters

elementTypestring?gate | star | deity | stem | palace

Example 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
GET/trpc/liuyao.calculate

Generate a Liuyao hexagram reading

Parameters

methodstringcoin | time | number
coinFlipsnumber[]?Array of 6 coin flip results (3=yang, 2=yin)
questionstring?Optional question
numbersnumber[]?Numbers for number method

Example 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
GET/trpc/meihua.calculate

Calculate a Meihua Yishu hexagram from numbers

Parameters

upperNumbernumberUpper trigram number
lowerNumbernumberLower trigram number
changingLinenumber?Changing line (1-6)
questionstring?Optional question

Example 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
GET/trpc/nameAnalysis.analyze

Analyze a Chinese name using numerology and Five Elements

Parameters

surnamestringSurname (姓)
givenNamestringGiven name (名)
genderstring?male | female

Example 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":"..."}}}}
GET/trpc/nameAnalysis.numerology

Look 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
GET/trpc/compatibility.zodiac

Chinese 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":"..."}}}}
GET/trpc/compatibility.birthday

Birthday-based compatibility analysis

Parameters

date1stringISO date YYYY-MM-DD
date2stringISO date YYYY-MM-DD

Example 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":"..."}}}}
GET/trpc/compatibility.bloodType

Blood type compatibility analysis

Parameters

type1stringA | B | AB | O
type2stringA | B | AB | O

Example 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
GET/trpc/auspicious.analyzeNumber

Analyze auspiciousness of a number (phone, license plate, ID, address)

Parameters

numberstringNumber string to analyze
contextstringphone | license_plate | id | address | general

Example 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
GET/trpc/almanac.daily

Get daily almanac data including twelve values, deities, and auspicious activities

Parameters

datestringDate in YYYY-MM-DD format

Example 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":[...]}}}}
GET/trpc/almanac.zodiacSign

Get Western and Chinese zodiac signs for a birth date

Parameters

birthDatestringBirth date in YYYY-MM-DD format

Example 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
GET/trpc/xiaoLiuRen.calculate

Six 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 | lost
questionstring?Optional question for context

Example 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
GET/trpc/daLiuRen.calculate

Four 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 | general
questionstring?Optional question for context

Example 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
GET/trpc/taiYi.calculate

72-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 | era
questionstring?Optional question for context

Example 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
GET/trpc/tarot.draw

Draw 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 draws

Example 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
GET/trpc/coinFlip.flip

Classic yes/no oracle with weighted probability and 7 domain-specific interpretations

Parameters

questionstring?Optional question for context
aspectstring?general | career | love | wealth | health | travel | question
flipsnumber?Number of flips 1–9 (default: 1)
seednumber?Optional seed for reproducible results

Example 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
GET/trpc/runes.cast

Cast 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 context
seednumber?Optional seed for reproducible casts

Example 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
GET/trpc/numerology.calculate

Pythagorean 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
GET/trpc/astrology.calculate

Sun, 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 context

Example 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":"..."}}}}