TimeQL Documentation

Resolve profiles, moments, relations, and ranked candidates from datetime + location. TimeQL returns structured signals with symbolic semantics. Your AI interprets above the line.

Get started →

import requests

resp = requests.post(
    "https://api.timeql.com/api/v1/natal_chart",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "test",
        "datetime": "2000-01-01T12:00:00",
        "location": "Tokyo",
    },
)
print(resp.json())

Quickstart

Three steps to your first API call.

Create an account

Get an API key

Create an API key from the Dashboard. The key is shown only once — store it securely.

Make your first request

Use the code below to resolve a natal chart.

import requests

resp = requests.post(
    "https://api.timeql.com/api/v1/natal_chart",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "test",
        "datetime": "2000-01-01T12:00:00",
        "location": "Tokyo",
    },
)
print(resp.json())

curl -X POST https://api.timeql.com/api/v1/natal_chart \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "test",
    "datetime": "2000-01-01T12:00:00",
    "location": "Tokyo"
  }'

Authentication

All API requests require an X-API-Key header. Create and manage keys from the Dashboard.

POST /api/v1/natal_chart HTTP/1.1
Host: api.timeql.com
Content-Type: application/json
X-API-Key: yao_sk_xxxxxxxxxxxxxxxxxxxxxxxx

Key management

Action	Description
Create	Issue a new key from the Dashboard. The key is shown only once.
Rotate	Revoke the old key and issue a new one. Both keys are valid during the transition period.
Revoke	Invalidate a key immediately. This action cannot be undone.

Credits

API requests are billed in credits. Endpoints are classified into 6 tiers by computational complexity.

Class	Credits	Example endpoints
Meta	0	`health`, `capabilities`, `taxonomy`
Light	1	`horoscope`, `sukuyo`
Core	5	`kanshi`, `kyusei`, `return_chart`
Standard	10	`natal_chart`, `synastry`, `transits`
Intensive	25	`qimen`, `bazi/compatibility`
Deep	100	`tekitenzui`, `jyotish`

Symbolic Semantics

TimeQL returns not only numeric outputs, but also structured symbolic semantics: elements, polarity, archetypes, relation categories, activation states, and ranked signals.

L0–L5: Computed by TimeQL

Layer	What it does	Example fields
L0 Input	Accept datetime + location	`datetime`, `timezone`, `location`
L1 Conversion	Calendar, stems, branches, positions	`pillars`, `rashi`, `house_cusps`
L2 Cycles	Time progression systems	`daiun`, `dasha`, `transits`
L3 Symbols	Attach meaning to computed values	`element`, `keywords`, `reading_note`
L4 Relations	Cross-entity relationships	`aspects`, `compatibility_score`, `convergence`
L5 Progression	Timeline, ranking, scoring	`timeline`, `best_slots[]`, `direction_rank[]`

L6: Interpretation — above the line

TimeQL does not generate final narrative. L6 interpretation is handled by your application, your AI, or by 八百占術 (YaoSenjutsu) as an orchestration layer.

The notes and reading_note fields in responses are structured symbolic descriptions (L3), not L6 narrative. They provide element associations, archetype keywords, and positional meanings that your interpretation layer can use as input.

出生図

POST /api/v1/natal_chart 10 credits

出生日時と場所から、惑星位置・ハウスカスプ・アスペクト・3区分4区分を含む完全な出生図を計算します。月のノード（北ノード・南ノード）を含む12天体に対応。

パラメータ

フィールド	型		説明
`name`	string	必須	対象者の名前
`datetime`	string	必須	出生日時（ISO 8601形式）
`location`	string	必須	出生地（都市名または緯度経度）
`house_system`	string	任意	ハウスシステム。デフォルト: `placidus`

リクエスト例

{
  "name": "田中太郎",
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo"
}

レスポンス例（抜粋）

{
  "name": "田中太郎",
  "planets": {
    "sun": {"longitude": 84.12, "sign": "Gemini", "degree": 24.12, "house": 10},
    "moon": {"longitude": 218.45, "sign": "Scorpio", "degree": 8.45, "house": 3},
    // ... 10天体 + North/South Node
  },
  "houses": [243.5, 271.2, /* ... 12カスプ */],
  "aspects": [...],
  "modalities": {"cardinal": 4, "fixed": 3, "mutable": 5},
  "elements": {"fire": 3, "earth": 2, "air": 4, "water": 3}
}

四柱推命

POST /api/v1/bazi 25 credits

四柱推命による命式を作成します。蔵干分野・通変星・十二運・神殺・大運を含む本格的な命式分析。用神判定と相性診断のサブエンドポイントも利用可能。

サブエンドポイント

/api/v1/bazi/yojin 用神判定

/api/v1/bazi/compatibility 相性診断

/api/v1/bazi/fortune 運勢分析

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	任意	出生地
`gender`	string	必須	`male` / `female`
`use_solar_time`	boolean	任意	真太陽時補正。デフォルト: `true`

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "gender": "male"
}

レスポンス例（抜粋）

{
  "pillars": {
    "year":  {"stem": "庚", "branch": "午"},
    "month": {"stem": "壬", "branch": "午"},
    "day":   {"stem": "丙", "branch": "辰"},
    "hour":  {"stem": "乙", "branch": "未"}
  },
  "zoukan": [...],
  "tsuhensei": [...],
  "daiun": [...],
  "kuubou": ["寅", "卯"]
}

滴天髄

POST /api/v1/tekitenzui 100 credits

滴天髄理論に基づく高度な命理分析を実行します。旺相休囚死・仮数測定・五行バランス補正・格局判定・用神判定・大運分析を含む包括的な分析。

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	任意	出生地
`gender`	string	必須	`male` / `female`

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "gender": "male"
}

算命学

POST /api/v1/sanmeigaku 25 credits

算命学に基づく陰占・陽占を計算します。二十八元蔵干・天冲殺・十大主星・十二大従星・大運を含む本格的な命式。

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	任意	出生地
`gender`	string	必須	`male` / `female`

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "gender": "male"
}

インド占星術

POST /api/v1/jyotish 25 credits

インド占星術のチャートを計算します。ラグナ・9グラハ・27ナクシャトラ・ヴァルガ・シャドバラ・アシュタカヴァルガ・ヨーガ・ヴィムショッタリーダシャーに対応。Lahiriアヤナムシャ使用。

サブエンドポイント

/api/v1/jyotish/gochara ゴーチャラ（トランジット）分析

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	必須	出生地
`gender`	string	任意	`male` / `female`

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo"
}

レスポンス例（抜粋）

{
  "lagna": {"rashi": "Tula", "degree": 15.42, "nakshatra": "Swati"},
  "grahas": {
    "surya": {"rashi": "Vrishabha", "degree": 0.68, "nakshatra": "Krittika"},
    "chandra": {"rashi": "Tula", "degree": 14.92, "nakshatra": "Swati"},
    // ... 9 Grahas
  },
  "vimshottari_dasha": {...},
  "shadbala": {...},
  "yogas": [...]
}

紫微斗数

POST /api/v1/ziweidoushu 25 credits

紫微斗数の命盤を作成します。十四主星・六吉星・六煞星・化曜の配置と十二宮の分析を返します。

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時（旧暦自動変換）
`gender`	string	必須	`male` / `female`
`location`	string	任意	出生地

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "gender": "male"
}

シナストリー

POST /api/v1/synastry 10 credits

二人の出生図を比較し、相性分析を行います。ハウスオーバーレイ、ハーモニックアスペクト、デイビソン関係チャートを含みます。

パラメータ

フィールド	型		説明
`person1`	object	必須	1人目の出生データ（`name`, `datetime`, `location`）
`person2`	object	必須	2人目の出生データ

リクエスト例

{
  "person1": {
    "name": "太郎",
    "datetime": "1990-06-15T14:30:00",
    "location": "Tokyo"
  },
  "person2": {
    "name": "花子",
    "datetime": "1992-03-20T09:00:00",
    "location": "Osaka"
  }
}

トリプルシナストリー

POST /api/v1/triple_synastry 10 credits

三人の相性を同時に分析します。グループ内の調和度、各人の役割（リーダー・メディエーター・カタリスト）を判定します。

パラメータ

フィールド	型		説明
`person1`	object	必須	1人目の出生データ
`person2`	object	必須	2人目の出生データ
`person3`	object	必須	3人目の出生データ

リクエスト例

{
  "person1": {"name": "A", "datetime": "1990-01-01T12:00:00", "location": "Tokyo"},
  "person2": {"name": "B", "datetime": "1991-06-15T08:00:00", "location": "Osaka"},
  "person3": {"name": "C", "datetime": "1992-12-25T20:00:00", "location": "Kyoto"}
}

コンポジット

POST /api/v1/composite 10 credits

二人の中間点から関係性の本質を示すコンポジットチャートを作成します。ミッドポイント方式とデイビソン方式に対応。

パラメータ

フィールド	型		説明
`person1`	object	必須	1人目の出生データ
`person2`	object	必須	2人目の出生データ
`method`	string	任意	`midpoint`（デフォルト）/ `davison`

リクエスト例

{
  "person1": {"name": "太郎", "datetime": "1990-06-15T14:30:00", "location": "Tokyo"},
  "person2": {"name": "花子", "datetime": "1992-03-20T09:00:00", "location": "Osaka"},
  "method": "midpoint"
}

四柱推命相性

POST /api/v1/bazi/compatibility 25 credits

2人の四柱推命チャートを比較し、五行の相性・日干の関係・地支の合冲を分析。恋愛・ビジネス・友人関係に対応。

パラメータ

名前	型	説明
`person1_datetime`	string	1人目の出生日時
`person2_datetime`	string	2人目の出生日時
`person1_gender`	string	1人目の性別（任意）
`person2_gender`	string	2人目の性別（任意）

算命学相性

POST /api/v1/sanmeigaku/compatibility 10 credits

2人の算命学チャートを比較。天中殺グループの組み合わせ・日干の五行相性・地支の位相法クロス分析による総合相性スコア。

パラメータ

名前	型	説明
`datetime_a`	string	1人目の生年月日
`datetime_b`	string	2人目の生年月日

九星気学相性

POST /api/v1/kyusei/compatibility 5 credits

2人の九星（本命星・月命星）の五行関係から相性を判定。相生・相剋・比和の関係性とアドバイス。

パラメータ

名前	型	説明
`person1_datetime`	string	1人目の生年月日
`person2_datetime`	string	2人目の生年月日

トランジット

POST /api/v1/transits 10 credits

指定期間のトランジットを計算します。現在の天体位置が出生図の天体に形成するアスペクトを検出し、影響の強さとタイミングを返します。

パラメータ

フィールド	型		説明
`name`	string	必須	対象者の名前
`datetime`	string	必須	出生日時
`location`	string	必須	出生地
`transit_date`	string	任意	トランジット日。デフォルト: 今日

リクエスト例

{
  "name": "田中太郎",
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "transit_date": "2026-03-19"
}

プログレッション

POST /api/v1/progressions 10 credits

セカンダリープログレッション（一日一年法）を計算します。進行した惑星位置と出生図へのアスペクトを返します。

パラメータ

フィールド	型		説明
`name`	string	必須	対象者の名前
`datetime`	string	必須	出生日時
`location`	string	必須	出生地
`progression_date`	string	任意	進行先の日付。デフォルト: 今日

リクエスト例

{
  "name": "田中太郎",
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "progression_date": "2026-03-19"
}

リターンチャート

POST /api/v1/return_chart 5 credits

ソーラーリターン、ルナーリターン、サターンリターン、ジュピターリターンを計算します。指定した天体が出生時の位置に戻る正確な日時とチャートを返します。

パラメータ

フィールド	型		説明
`name`	string	必須	対象者の名前
`datetime`	string	必須	出生日時
`location`	string	必須	出生地
`return_type`	string	必須	`solar` / `lunar` / `saturn` / `jupiter`
`year`	integer	任意	計算対象年。デフォルト: 今年

リクエスト例

{
  "name": "田中太郎",
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "return_type": "solar",
  "year": 2026
}

デイリーホロスコープ

POST /api/v1/horoscope 1 credit

12星座のデイリーホロスコープを取得します。実際の惑星位置に基づくダイナミックなラッキーカラー・ラッキーナンバーを含みます。出生データ不要。

パラメータ

フィールド	型		説明
`date`	string	必須	日付（YYYY-MM-DD）
`sign`	string	任意	星座名。省略時は全12星座を返す

リクエスト例

{
  "date": "2026-03-19",
  "sign": "pisces"
}

干支

POST /api/v1/kanshi 5 credits

年月日時の四柱干支を計算します。六十干支、十二運、空亡、納音に対応。

パラメータ

フィールド	型		説明
`datetime`	string	必須	日時
`location`	string	任意	場所（地方時補正に使用）
`gender`	string	任意	`male` / `female`（大運計算に使用）

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo",
  "gender": "male"
}

宿曜

POST /api/v1/sukuyo 1 credit

宿曜経に基づく二十七宿の判定と相性分析を行います。凌犯期間の判定にも対応。

パラメータ

フィールド	型		説明
`datetime`	string	必須	日時
`location`	string	任意	場所（月位置の精密計算に使用）

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo"
}

三九の秘法

POST /api/v1/sanku 1 credit

宿曜の三九の秘法（六害宿）を計算します。命・意・事・克・聚・同の六分類で関係性を判定。

パラメータ

フィールド	型		説明
`datetime`	string	必須	日時
`location`	string	任意	場所

リクエスト例

{
  "datetime": "1990-06-15T14:30:00"
}

九星気学

POST /api/v1/kyusei 5 credits

九星気学に基づく本命星・月命星・日命星を判定します。吉方位・相性・運勢ガイダンスのサブエンドポイントも利用可能。

サブエンドポイント

/api/v1/kyusei/directions 吉方位判定

/api/v1/kyusei/compatibility 相性判定

/api/v1/kyusei/guidance 運勢ガイダンス

パラメータ

フィールド	型		説明
`datetime`	string	必須	出生日時
`location`	string	任意	出生地

リクエスト例

{
  "datetime": "1990-06-15T14:30:00",
  "location": "Tokyo"
}

奇門遁甲

POST /api/v1/qimen 25 credits

奇門遁甲の時盤を計算します。天盤・地盤・八門・九星・八神・十干の配置と吉方位を判定。拆補法に準拠。

サブエンドポイント

/api/v1/qimen/matrix 九宮マトリクス形式で取得

パラメータ

フィールド	型		説明
`datetime`	string	必須	日時
`location`	string	任意	場所（節気判定に使用）

リクエスト例

{
  "datetime": "2026-03-19T10:00:00",
  "location": "Tokyo"
}

風水

POST /api/v1/fengshui 10 credits

住む人の方位相性・建物のエネルギー分布・年ごとの方位運を統合した風水分析。パラメータの有無で分析範囲を自動決定。方位は度数または方位名（北/南/子/午等）で指定可能。

パラメータ

名前	型	説明
`birth_year`	int	生年（個人の方位相性分析用）
`gender`	string	性別 male/female
`building_year`	int	建築年（建物エネルギー分析用）
`facing_direction`	string	建物の向き（方位名: 北/南/子/午等）
`entrance_direction`	string	玄関の向き（年運分析用）
`target_year`	int	年運の対象年

滴天髄遁甲

POST /api/v1/tekitenzui_qimen 100 credits

出生データから個人の五行プロファイルを生成し、時間帯×方角の吉凶を個人化。万人共通の吉方位を、その人だけの吉方位に変換する。

パラメータ

名前	型	説明
`birth_datetime`	string	出生日時（ISO8601）
`gender`	string	性別 male/female
`target_datetime`	string	方位を見る対象日時
`home_longitude`	float	自宅の経度（自然時計算用）

滴天髄風水

POST /api/v1/tekitenzui_fengshui 100 credits

出生データから個人の五行プロファイルを生成し、風水の方位スコアを個人化。8方位のパーソナライズドランキングを生成。

パラメータ

名前	型	説明
`birth_datetime`	string	出生日時（ISO8601）
`gender`	string	性別 male/female
`building_year`	int	建築年（建物エネルギー分析用）
`facing_direction`	string	建物の向き（方位名）
`entrance_direction`	string	玄関の向き

六壬神課

POST /api/v1/liuren 25 credits

六壬神課の課式を立てます。四課三伝・天将・天盤地盤を計算し、課の種類（賊剋・比用・涉害・遥剋・昴星・伏吟・返吟）を判定します。

パラメータ

フィールド	型		説明
`datetime`	string	必須	日時
`location`	string	任意	場所（月将計算に使用）

リクエスト例

{
  "datetime": "2026-03-19T10:00:00",
  "location": "Tokyo"
}

イレクション

POST /api/v1/election 10 credits

イレクショナル占星術に基づき、特定の目的に最適な日時を選択します。結婚、起業、契約などの目的に対応。

パラメータ

フィールド	型		説明
`purpose`	string	必須	目的（例: `marriage`, `business`）
`location`	string	必須	場所
`start_date`	string	必須	検索開始日
`end_date`	string	必須	検索終了日

リクエスト例

{
  "purpose": "business",
  "location": "Tokyo",
  "start_date": "2026-04-01",
  "end_date": "2026-04-30"
}

姓名判断

POST /api/v1/seimei 5 credits

姓名判断による三格（天格・人格・地格）の画数分析を行います。四柱推命の喜忌と連動した名前の提案機能も利用可能。

サブエンドポイント

/api/v1/seimei/suggest 吉名候補の提案

パラメータ

フィールド	型		説明
`family_name`	string	必須	姓（漢字）
`given_name`	string	必須	名（漢字）

リクエスト例

{
  "family_name": "田中",
  "given_name": "太郎"
}

Agent Integration (GPTs / LLM)

Connect TimeQL to OpenAI GPTs, Claude, or any LLM agent. TimeQL provides L0–L5 structured signals; your agent handles L6 interpretation.

1. Get an API key

Dashboard → API Keys

2. Authentication setup (GPTs)

Auth Type	API Key
API Key	Paste the key from your Dashboard
Auth Type	Custom
Custom Header Name	`X-Api-Key`

3. Generate schema URL

GPTs Actions support up to 30 endpoints per action. Select the endpoints you need below, then import the generated URL in GPTs → Actions → Import from URL.

Select endpoints to include (max 30):

0 / 29 selected

4. System prompt for L6 interpretation

Add the following to your agent's system prompt. This establishes the boundary between TimeQL's computed signals (L0–L5) and the agent's interpretation layer (L6).

You are an interpretation layer on top of TimeQL.

TimeQL boundary:
- L0–L5 (input → symbols → relations → progression) = computed by TimeQL.
  Treat these fields as ground truth. Never invent calculations.
- L6 (interpretation) = your responsibility.
  Transform structured signals into contextual, human-readable insight.

Rules:
1. Always call TimeQL for computation. Do not guess scores or positions.
2. Use "notes" and "reading_note" fields as structured symbolic input (L3),
   not as final narrative. Expand them with context.
3. Clearly separate computed facts from your interpretation.
   e.g. "TimeQL reports Jupiter in house 10 (L2). This suggests..."
4. When multiple systems are queried, report convergence and divergence
   explicitly. Do not cherry-pick agreeing signals.
5. Ask for datetime, location, and gender before calling Person endpoints.

Query family guide:
- Person: natal_chart, bazi, tekitenzui, jyotish, sanmeigaku, ziweidoushu
- Moment: transits, qimen, kyusei, liuren
- Relation: synastry, composite, bazi/compatibility
- Search: election, qimen/matrix, seimei/suggest
- Meta: capabilities (discover available endpoints and costs)

5. Example: L6 in action

This demonstrates how a GPT agent transforms TimeQL signals into interpretation while maintaining the boundary.

// Agent receives from TimeQL (L0–L5):
{
  "day_master": { "kanji": "辛", "nature": "宝石" },
  "yojin": { "yojin": "木", "yojin_category": "財星" },
  "notes": {
    "personality": "基本性格: 感受性が鋭く美的センスに優れる...",
    "career": "日主適職キーワード: 美意識、感受性、プライド..."
  }
}

// Agent produces (L6 interpretation):
"TimeQL identifies 辛 (polished metal) as day master with 木 (wood)
as the operative element in the wealth category.
The structured notes indicate strong aesthetic sensitivity.

My interpretation: This profile suits creative industries where
refined taste translates into value — design, curation, luxury goods.
The wood element as yojin suggests growth through outward expression
rather than internal accumulation."

Errors

The API returns standard HTTP status codes. Error responses include a JSON body with details.

{
  "error": {
    "code": "invalid_parameter",
    "message": "datetime is required"
  }
}

コード	名前	説明
200	OK	Request succeeded
400	Bad Request	Invalid parameters (missing required fields, format errors)
401	Unauthorized	API key missing or invalid
403	Forbidden	Insufficient credits or plan limit exceeded
429	Too Many Requests	Rate limit exceeded. Check the `Retry-After` header
500	Internal Server Error	Server-side error. Contact support if the issue persists

Rate Limits

Request rates are limited by plan. Exceeding the limit returns a 429 status.

プラン	RPM	日次クォータ	月次クォータ
Free	10	120	3,000
Builder	25	600	15,000
Growth	90	4,800	120,000
Scale	250	18,000	450,000

Response headers

Every response includes headers indicating current usage.

Header	Description
`X-RateLimit-Limit`	Max requests per minute
`X-RateLimit-Remaining`	Remaining requests
`X-RateLimit-Reset`	Seconds until reset
`X-Credits-Remaining`	Remaining credits

TimeQL Documentation

Quickstart

Create an account

Get an API key

Make your first request

Authentication

Key management

Credits

Symbolic Semantics

L0–L5: Computed by TimeQL

L6: Interpretation — above the line

出生図

パラメータ

リクエスト例

レスポンス例（抜粋）

四柱推命

サブエンドポイント

パラメータ

リクエスト例

レスポンス例（抜粋）

滴天髄

パラメータ

リクエスト例

算命学

パラメータ

リクエスト例

インド占星術

サブエンドポイント

パラメータ

リクエスト例

レスポンス例（抜粋）

紫微斗数

パラメータ

リクエスト例

シナストリー

パラメータ

リクエスト例

トリプルシナストリー

パラメータ

リクエスト例

コンポジット

パラメータ

リクエスト例

四柱推命 相性

パラメータ

算命学 相性

パラメータ

九星気学 相性

パラメータ

トランジット

パラメータ

リクエスト例

プログレッション

パラメータ

リクエスト例

リターンチャート

パラメータ

リクエスト例

デイリーホロスコープ

パラメータ

リクエスト例

干支

パラメータ

リクエスト例

宿曜

パラメータ

リクエスト例

三九の秘法

パラメータ

リクエスト例

九星気学

サブエンドポイント

パラメータ

リクエスト例

奇門遁甲

サブエンドポイント

パラメータ

リクエスト例

風水

パラメータ

四柱推命相性

算命学相性

九星気学相性