API完全ガイド - 開発者向け
築古不動産投資シミュレーターは、開発者が独自のアプリケーションやツールを構築するための包括的なAPIを提供しています。REST API、MCP（Model Context Protocol）対応、リアルタイム更新まで、開発に必要な全ての情報を詳しく解説します。
🚀 API の特徴
RESTful設計：標準的なHTTPメソッドとステータスコード
JSON形式：すべてのリクエスト・レスポンスはJSON
OAuth認証：セキュアなGoogle/GitHub認証
MCP対応：AIアシスタントとの直接連携
リアルタイム更新：WebSocketによるライブ計算
型安全性：TypeScript型定義提供
🔐 認証システム
OAuth 2.0 認証フロー
セキュリティを重視し、OAuth 2.0を採用しています。
📋 認証手順
認証プロバイダー選択
Google OAuth 2.0
GitHub OAuth
認証URL生成
GET /auth/login?provider=google
GET /auth/login?provider=github
コールバック処理
GET /auth/callback?code=AUTH_CODE&state=STATE
JWTトークン取得
{
"access_token": "eyJhbGciOiJIUzI1NaI1NiIsInR5cCI6IkpXVCJ9...",
"refresh_token": "eyJhbGciOiJIUzI1NaI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600,
"token_type": "Bearer"
}
API認証ヘッダー
すべてのAPIリクエストには、Authorizationヘッダーが必要です。
🔑 認証ヘッダー例
Authorization: Bearer eyJhbGciOiJIUzI1NaI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
User-Agent: YourApp/1.0
トークンリフレッシュ
POST /auth/refresh
Content-Type: application/json
{
"refresh_token": "eyJhbGciOiJIUzI1NaI1NiIsInR5cCI6IkpXVCJ9..."
}
// Response
{
"access_token": "NEW_ACCESS_TOKEN",
"expires_in": 3600
}
📡 主要エンドポイント
シミュレーション管理
📊 GET /api/simulations
説明：ユーザーのシミュレーション一覧を取得
クエリパラメータ
page (optional): ページ番号 (default: 1)
limit (optional): 取得件数 (default: 20, max: 100)
sort (optional): ソート順 (created_at, updated_at, property_price)
order (optional): ソート方向 (asc, desc)
property_type (optional): 物件種別フィルター (house, apartment)
レスポンス例
{
"simulations": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"title": "築30年戸建て物件",
"property_type": "house",
"property_price": 10000000,
"annual_rent": 1200000,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T15:45:00Z",
"share_code": "abc123def456",
"results": {
"gross_yield": 12.0,
"net_yield": 9.7,
"monthly_cash_flow": 42500,
"roi": 15.2,
"npv": 2450000,
"irr": 18.5
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45,
"total_pages": 3
}
}
📝 POST /api/simulations
説明：新しいシミュレーションを作成
リクエストボディ
{
"title": "築25年木造戸建て投資",
"property_type": "house",
"property_price": 8000000,
"land_price": 3000000,
"building_price": 5000000,
"annual_rent": 960000,
"vacancy_rate": 5,
"expense_rate": 20,
"renovation_cost": 500000,
"broker_fee_rate": 3,
"use_loan": true,
"loan_amount": 6000000,
"loan_interest_rate": 2.5,
"loan_term": 25,
"is_old_property": true,
"building_age": 25,
"structure_type": "wood",
"depreciation_method": "straight_line",
"discount_rate": 5,
"holding_period": 10,
"exit_cap_rate": 8
}
レスポンス例
{
"id": "789e0123-e89b-12d3-a456-426614174000",
"title": "築25年木造戸建て投資",
"created_at": "2024-01-15T16:20:00Z",
"share_code": "xyz789abc123",
"results": {
"gross_yield": 12.0,
"net_yield": 8.9,
"monthly_cash_flow": 35200,
"annual_cash_flow": 422400,
"roi": 14.1,
"npv": 1850000,
"irr": 16.8,
"depreciation": {
"annual_amount": 1136364,
"remaining_years": 4,
"total_depreciation": 4545456
},
"tax_simulation": {
"personal_tax": 63360,
"corporate_tax": 45552,
"tax_savings": 17808
}
}
}
🔍 GET /api/simulations/{id}
説明：特定のシミュレーション詳細を取得
パスパラメータ
id: シミュレーションID (UUID)
レスポンス例
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"title": "築30年戸建て物件",
"property_type": "house",
"property_price": 10000000,
"land_price": 4000000,
"building_price": 6000000,
"annual_rent": 1200000,
"vacancy_rate": 5,
"expense_rate": 20,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T15:45:00Z",
"results": {
"basic_metrics": {
"gross_yield": 12.0,
"net_yield": 9.7,
"monthly_cash_flow": 42500,
"annual_cash_flow": 510000,
"roi": 15.2
},
"advanced_metrics": {
"npv": 2450000,
"irr": 18.5,
"payback_period": 6.2,
"profitability_index": 1.45
},
"cash_flow_projection": [
{
"year": 1,
"rental_income": 1140000,
"expenses": 240000,
"loan_payment": 420000,
"depreciation": 1363636,
"net_cash_flow": 480000,
"cumulative_cash_flow": 480000
}
],
"sensitivity_analysis": {
"rent_sensitivity": {
"-20%": { "net_yield": 5.8, "roi": 8.1 },
"-10%": { "net_yield": 7.7, "roi": 11.7 },
"+10%": { "net_yield": 11.7, "roi": 18.7 },
"+20%": { "net_yield": 13.7, "roi": 22.3 }
}
}
}
}
リアルタイム計算
⚡ POST /api/simulations/calculate
説明：保存せずにリアルタイム計算を実行
リクエストボディ
{
"property_price": 8000000,
"annual_rent": 960000,
"vacancy_rate": 5,
"expense_rate": 20,
"use_loan": true,
"loan_amount": 6000000,
"loan_interest_rate": 2.5,
"loan_term": 25
}
レスポンス例
{
"calculation_id": "calc_789xyz",
"timestamp": "2024-01-15T16:45:30Z",
"results": {
"gross_yield": 12.0,
"net_yield": 8.64,
"monthly_cash_flow": 31200,
"annual_cash_flow": 374400,
"roi": 18.72,
"total_initial_cost": 2000000,
"monthly_loan_payment": 26847
}
}
感度分析とストレステスト
📈 POST /api/simulations/{id}/sensitivity
説明：感度分析を実行
リクエストボディ
{
"parameters": ["annual_rent", "vacancy_rate", "expense_rate", "loan_interest_rate"],
"ranges": {
"annual_rent": { "min": -30, "max": 30, "step": 10 },
"vacancy_rate": { "min": 0, "max": 25, "step": 5 },
"expense_rate": { "min": 15, "max": 35, "step": 5 },
"loan_interest_rate": { "min": 1, "max": 5, "step": 0.5 }
},
"target_metrics": ["net_yield", "roi", "monthly_cash_flow"]
}
レスポンス例
{
"analysis_id": "sens_456def",
"created_at": "2024-01-15T17:00:00Z",
"results": {
"tornado_chart": [
{
"parameter": "annual_rent",
"impact_range": { "min": -3.2, "max": 3.2 },
"sensitivity_score": 0.85
},
{
"parameter": "vacancy_rate",
"impact_range": { "min": -2.1, "max": 0 },
"sensitivity_score": 0.65
}
],
"heatmap": {
"annual_rent_vs_vacancy_rate": [
{ "x": -20, "y": 0, "net_yield": 11.2 },
{ "x": -20, "y": 10, "net_yield": 9.8 },
{ "x": 0, "y": 0, "net_yield": 9.7 },
{ "x": 20, "y": 0, "net_yield": 8.1 }
]
}
}
}
🤖 MCP (Model Context Protocol) 対応
AIアシスタントが直接APIを操作できるMCP仕様に対応しています。
🔧 MCP サーバー接続
サーバー情報
エンドポイント: wss://kominka-apart-sim.vercel.app/mcp
プロトコル: WebSocket over TLS
認証: Bearer Token (JWT)
利用可能なツール
create_simulation: 新規シミュレーション作成
get_simulation: シミュレーション詳細取得
list_simulations: シミュレーション一覧取得
calculate_metrics: リアルタイム計算
run_sensitivity_analysis: 感度分析実行
run_stress_test: ストレステスト実行
Claude Desktop設定例
{
"mcpServers": {
"kominka-simulator": {
"command": "node",
"args": ["path/to/kominka-mcp-server.js"],
"env": {
"API_BASE_URL": "https://kominka-apart-sim.vercel.app/api",
"AUTH_TOKEN": "your_jwt_token_here"
}
}
}
}
🔄 WebSocket リアルタイム更新
⚡ リアルタイム計算
パラメータ変更時のリアルタイム計算結果をWebSocketで配信
接続
wss://kominka-apart-sim.vercel.app/ws/calculations
Headers:
Authorization: Bearer YOUR_JWT_TOKEN
メッセージ形式
// 計算要求
{
"type": "calculate",
"params": {
"property_price": 8000000,
"annual_rent": 960000,
"vacancy_rate": 5
}
}
// 計算結果
{
"type": "result",
"timestamp": "2024-01-15T17:30:00Z",
"data": {
"gross_yield": 12.0,
"net_yield": 9.12,
"monthly_cash_flow": 34500
}
}
❌ エラーハンドリング
🚨 HTTPステータスコード
200 - 成功
201 - 作成成功
400 - リクエストエラー（バリデーション失敗）
401 - 認証エラー
403 - 権限エラー
404 - リソースが見つからない
429 - レート制限exceeded
500 - サーバーエラー
エラーレスポンス形式
{
"error": {
"code": "VALIDATION_ERROR",
"message": "入力値が無効です",
"details": [
{
"field": "property_price",
"message": "物件価格は100万円以上である必要があります"
},
{
"field": "annual_rent",
"message": "年間家賃収入は必須です"
}
]
},
"request_id": "req_123abc456def"
}
よくあるエラーと対処法
401 Unauthorized: JWTトークンの有効期限切れ → リフレッシュまたは再認証
429 Too Many Requests: レート制限 → 時間をおいて再試行
400 Bad Request: 入力値検証エラー → リクエストパラメータを確認
⚡ レート制限
📊 制限内容
一般API: 1000リクエスト/時間
計算API: 500リクエスト/時間
WebSocket: 100メッセージ/分
レスポンスヘッダー
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 994
X-RateLimit-Reset: 1642694400
📝 TypeScript 型定義
🎯 型定義パッケージ
npm install @kominka-sim/types
基本的な使用例
import {
SimulationRequest,
SimulationResponse,
CalculationResult
} from '@kominka-sim/types'
const createSimulation = async (
params: SimulationRequest
): Promise => {
const response = await fetch('/api/simulations', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(params)
})
return response.json()
}
🛠️ SDK とクライアントライブラリ
📦 JavaScript/TypeScript SDK
npm install @kominka-sim/sdk
import { KominkaSimClient } from '@kominka-sim/sdk'
const client = new KominkaSimClient({
baseURL: 'https://kominka-apart-sim.vercel.app/api',
token: 'your_jwt_token'
})
// シミュレーション作成
const simulation = await client.simulations.create({
title: 'Test Simulation',
property_price: 10000000,
annual_rent: 1200000
})
// リアルタイム計算
const result = await client.calculations.calculate({
property_price: 8000000,
annual_rent: 960000
})
🐍 Python SDK
pip install kominka-sim-python
from kominka_sim import KominkaSimClient
client = KominkaSimClient(
base_url='https://kominka-apart-sim.vercel.app/api',
token='your_jwt_token'
)
# シミュレーション作成
simulation = client.simulations.create(
title='Test Simulation',
property_price=10000000,
annual_rent=1200000
)
# 感度分析
analysis = client.analysis.sensitivity(
simulation_id=simulation.id,
parameters=['annual_rent', 'vacancy_rate']
)
💡 開発者向けベストプラクティス
認証トークンの管理
トークンを安全に保存（環境変数、キーチェーン等）
有効期限切れの自動検知とリフレッシュ
リフレッシュトークンのローテーション対応
エラーハンドリング
指数バックオフによるリトライ実装
ネットワークエラーと API エラーの区別
ユーザーフレンドリーなエラーメッセージ
パフォーマンス最適化
リクエストのバッチ処理
WebSocket活用でリアルタイム更新
レスポンスキャッシュの適切な実装
セキュリティ
HTTPS必須（HTTPSでない場合はエラー）
機密データのログ出力防止
入力値の適切なバリデーション
監視とログ
API使用量の監視
エラー率の追跡
パフォーマンスメトリクスの収集
🚀 開発環境セットアップ
1. 開発者アカウント作成
築古不動産投資シミュレーターにログイン
設定ページから「開発者モード」を有効化
APIキーを生成（OAuth認証の場合は不要）
2. ローカル開発環境
# 環境変数設定
export KOMINKA_API_BASE_URL="https://kominka-apart-sim.vercel.app/api"
export KOMINKA_ACCESS_TOKEN="your_jwt_token"
# テスト実行
curl -H "Authorization: Bearer $KOMINKA_ACCESS_TOKEN" \
"$KOMINKA_API_BASE_URL/simulations"
3. 開発用Webhook
開発・テスト用のWebhookエンドポイントを提供：
POST /api/webhooks/test
{
"url": "https://your-dev-server.com/webhook",
"events": ["simulation.created", "calculation.completed"]
}