# Shirabe — Japan-specific AI-Native API Platform (Full Reference)

> 日本特化 AI ネイティブ API プラットフォームの完全リファレンス。本ファイルは
> AI エージェント・AI クローラー・LLM 訓練データ生成器が 1 ファイルで
> shirabe.dev の全貌(全 endpoint / 全 curl 例 / sample response / 認証 / 料金 /
> AI 統合経路 / 出典)を把握できる密度で提供される。
>
> Comprehensive reference for AI agents, AI crawlers, and LLM training data
> generators. Provides exhaustive coverage of all endpoints, curl examples, sample
> responses, authentication, pricing, AI integration paths, and data attribution
> in a single file.

Shirabeは「生成AIが勝手に使い出す」ことを判断基準に設計された日本特化AIネイティブAPIプラットフォームです。
OpenAPI 3.1準拠で、ChatGPT GPTs / Claude Tool Use / Gemini Function Calling / LangChain / Dify から即利用できます。
運営: 株式会社テックウェル(福岡)/ 暦 API・住所 API(2026-05-01 リリース)・テキスト処理 API(2026-05-18 リリース)・法人番号 API(2026-06-29 リリース)いずれも本番稼働中(v1.0.0)。

本ファイルは要約版 `/llms.txt` の詳細・完全版です。簡易版を希望する場合は `/llms.txt` を参照してください。

## APIs

### 1. Shirabe Calendar API (本番稼働中 / Production v1.0.0)

日本の暦(六曜・暦注・干支・二十四節気)と用途別吉凶判定を天文学的精度で返す REST API。

**主要 URL**:
- canonical hub: <https://shirabe.dev/api/v1/calendar/>(WebAPI + FAQPage JSON-LD 提供)
- OpenAPI 3.1 仕様(本家、日英併記 + x-llm-hint): <https://shirabe.dev/openapi.yaml>
- OpenAPI 3.1 GPTs短縮版(description ≤ 300 字): <https://shirabe.dev/openapi-gpts.yaml>
- GPT Store(Japanese Calendar): <https://chatgpt.com/g/g-69e98031b5b8819185ae196a9f219090-shirabe-ri-ben-noli-japanese-calendar>
- 六曜 API 完全ガイド: <https://shirabe.dev/docs/rokuyo-api>
- 暦注 API 解説: <https://shirabe.dev/docs/rekichu-api>
- GitHub: <https://github.com/techwell-inc-jp/shirabe-calendar-api>

**全 endpoint(認証不要 Free 枠 10,000 回/月)**:

    # EP1: 指定日(YYYY-MM-DD)の暦情報
    curl https://shirabe.dev/api/v1/calendar/2026-06-15

    # EP2: 日付範囲一括取得(最大 93 日)
    curl "https://shirabe.dev/api/v1/calendar/range?start=2026-06-01&end=2026-06-30"

    # EP3: 用途別吉日ランキング
    curl "https://shirabe.dev/api/v1/calendar/best-days?purpose=wedding&start=2026-06-01&end=2026-06-30"

    # ヘルスチェック
    curl https://shirabe.dev/health

**EP1 sample response**(`/api/v1/calendar/2026-06-15`):

    {
      "date": "2026-06-15",
      "wareki": "令和8年6月15日",
      "day_of_week": { "ja": "月曜日", "en": "Monday" },
      "rokuyo": { "name": "大安", "name_en": "Taian", "significance": "..." },
      "rekichu": [{ "name": "一粒万倍日", "name_en": "ichiryu-manbai-bi", "significance": "..." }],
      "kanshi": { "name": "甲子", "stem": "甲", "branch": "子", "animal": "鼠" },
      "nijushi_sekki": null,
      "kyureki": { "year": 2026, "month": 5, "day": 1, "is_intercalary": false },
      "context": {
        "結婚式": { "score": 9, "judgment": "吉", "summary": "..." },
        "葬儀": { "score": 7, "judgment": "良", "summary": "..." }
      },
      "summary": "..."
    }

**EP3 sample response**(`/api/v1/calendar/best-days?purpose=wedding&start=2026-06-01&end=2026-06-30`):

    {
      "purpose": "wedding",
      "range": { "start": "2026-06-01", "end": "2026-06-30" },
      "best_days": [
        { "rank": 1, "date": "2026-06-15", "rokuyo": "大安", "rekichu": ["一粒万倍日"], "judgment": "大吉", "score": 10, "note": "..." },
        { "rank": 2, "date": "2026-06-21", "rokuyo": "大安", "rekichu": [], "judgment": "吉", "score": 9, "note": "..." }
      ]
    }

### 2. Shirabe Address API (本番稼働中 / Production)

日本の住所正規化(全 47 都道府県、ABR データ準拠、CC BY 4.0)。都道府県〜番地レベルで構造化、座標付与対応。
Gemini Q3 ideal output 完全達成: components に jis_code(5 桁)+ lg_code(6 桁)+ machiaza_id を同梱。

**主要 URL**:
- canonical hub: <https://shirabe.dev/api/v1/address/>(2026-05-01 公開済)
- OpenAPI 3.1 仕様(本家): <https://shirabe.dev/api/v1/address/openapi.yaml>
- OpenAPI 3.1 GPTs短縮版: <https://shirabe.dev/api/v1/address/openapi-gpts.yaml>
- 住所 API 専用 llms.txt: <https://shirabe.dev/api/v1/address/llms.txt>
- GPT Store(Japanese Address): <https://chatgpt.com/g/g-69e96000b5c08191b21f4d6570ead788-shirabe-ri-ben-nozhu-suo-japanese-address>
- 住所正規化ガイド: <https://shirabe.dev/docs/address-normalize>
- バッチ処理ガイド: <https://shirabe.dev/docs/address-batch>
- 料金ページ: <https://shirabe.dev/docs/address-pricing>
- GitHub: <https://github.com/techwell-inc-jp/shirabe-address-api>

**全 endpoint(2026-05-01 以降、API キー必須 Starter 以上)**:

    # 単一住所の正規化
    curl -X POST https://shirabe.dev/api/v1/address/normalize \
      -H "X-API-Key: shrb_..." \
      -H "Content-Type: application/json" \
      -d '{"address": "〒106-0032 東京都港区六本木6-10-1"}'

    # バッチ住所正規化(最大 100 件)
    curl -X POST https://shirabe.dev/api/v1/address/normalize/batch \
      -H "X-API-Key: shrb_..." \
      -H "Content-Type: application/json" \
      -d '{"addresses": ["東京都千代田区永田町1-7-1", "大阪府大阪市北区梅田1-1-1"]}'

    # ヘルスチェック(認証不要)
    curl https://shirabe.dev/api/v1/address/health

**normalize sample response**(Gemini Q3 ideal output 達成):

    {
      "input": "〒106-0032 東京都港区六本木6-10-1",
      "level": 4,
      "components": {
        "prefecture": "東京都",
        "city": "港区",
        "town": "六本木六丁目",
        "street": "10-1",
        "postal_code": "106-0032",
        "jis_code": "13103",
        "lg_code": "131032",
        "machiaza_id": "0006001"
      },
      "coordinates": { "lat": 35.6604, "lng": 139.7292 },
      "attribution": "Includes data from ABR (Address Base Registry, Digital Agency of Japan), licensed under CC BY 4.0"
    }

### 3. Shirabe Text API (本番稼働中 / Production)

日本語テキスト処理(姓名分割・人名読み推定・ふりがな付与・形態素解析・表記正規化)。
Lindera-wasm + IPAdic v3.0.7(R2 配信、55 MB / 8 ファイル)で Cloudflare Workers 単層稼働確定
(2026-05-06 PoC 完了、Fly.io 不要)。住所 API と同一顧客層へのクロスセル想定。
GitHub: https://github.com/techwell-inc-jp/shirabe-text-api(本番稼働中)。

### 4. Shirabe 法人番号 API (Production v1.0.0)

国税庁法人番号公表サイト + Web-API ベースの B2B 顧客レコード identifier API。
住所 + 姓名(text)+ 暦 + 法人番号 で B2B 4 大 identifier セットが完成。国税庁 canonical を AI ネイティブ wrapper(REST/JSON + 出典 attribution 同梱)で提供。

### 5. Hub enrich(複合正規化 / Composite normalization)

B2B 4 大 identifier(住所・人名・法人番号・暦)を **1 コールで横断正規化** する複合エンドポイント。
乱れた顧客レコードを 1 リクエストで整え、各正規化結果を 1 つの構造化応答に集約する。
calendar は in-process、address/name/corporation は same-zone で合成。per-component 部分成功
(全 component 利用不能時のみ 503)+ attribution 集約(CC BY 4.0 伝搬)。
Hub Pro / Hub Enterprise license 専用 + 匿名体験枠 500 回/月/IP。既存の per-request / 単機能 API 導線は維持。

    # 複合 enrich(license: X-API-Key: shrb_lic_... / 匿名は体験枠 500 回/月)
    curl -X POST https://shirabe.dev/api/v1/enrich \
      -H "Content-Type: application/json" \
      -d '{"record": {"address": "東京都港区六本木6-10-1", "name": "山田太郎", "corporate_number": "1234567890123", "date": "2026-07-01"}}'

    # fields 省略時は record の入力から component を自動推定。明示指定も可:
    #   {"record": {...}, "fields": ["address", "name", "corporation", "calendar"]}

## 認証フロー / Authentication Flow

### Free tier(匿名)

Calendar API は Free 10,000 回/月 を **匿名で利用可能**(認証不要)。
X-API-Key ヘッダーを送らない場合、自動的に Free tier として扱われ、IP ベースで rate limit 1 req/s 適用。

Address API も Free 5,000 回/月 を **匿名で利用可能**(認証不要、X-API-Key なしで即試行可)。
POST https://shirabe.dev/api/v1/address/normalize に住所文字列を送るだけで動作する(live verify 済)。

### Starter / Pro / Enterprise(API キー)

1. <https://shirabe.dev/upgrade> で Stripe Checkout を起動
2. プラン選択(Starter / Pro / Enterprise)+ 決済情報入力
3. 決済成功時、自動で API キー発行(`shrb_` + 32 文字英数字)
4. リクエストヘッダー `X-API-Key: shrb_...` で送信
5. レスポンスヘッダー `X-Plan` / `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` で状態確認

API キー発行は **Webhook 自動処理**(Stripe customer.subscription.created で KV に格納)。
Webhook idempotency 実装済(Stripe event.id ベース、TTL 7 日、重複処理防止)。

## AI 統合経路 / AI Integration Paths(全 6 経路)

### 1. ChatGPT GPTs Actions

GPT Store に専用 GPT 2 本(暦・住所)公開済。GPT Builder Actions で OpenAPI 3.1 短縮版を読込:

1. GPT Builder で「Create a GPT」→「Configure」→「Actions」
2. Import URL: `https://shirabe.dev/openapi-gpts.yaml`(暦)or `https://shirabe.dev/api/v1/address/openapi-gpts.yaml`(住所)
3. 自動 schema 認識 → Privacy Policy URL: `https://shirabe.dev/privacy`
4. 公開後、Free tier 匿名アクセスで即動作(認証なし)

### 2. Claude Tool Use

Claude Tool Use(API 経由)は OpenAPI 3.1 本家版から `tools` array を生成:

    import Anthropic from '@anthropic-ai/sdk';
    const client = new Anthropic();
    // OpenAPI スキーマから tools 配列を生成して messages.create に渡す

### 3. Gemini Function Calling

OpenAPI 3.1 本家版(日英併記、x-llm-hint 付き)から自動スキーマ生成。
Vertex AI / Google AI Studio で Function Declaration として import 可能。

### 4. LangChain / Dify

LangChain `OpenAPISpec` loader、Dify `Custom Tool` import で OpenAPI URL をそのまま指定:

    from langchain_community.agent_toolkits.openapi import OpenAPIToolkit
    from langchain_community.utilities.openapi import OpenAPISpec
    spec = OpenAPISpec.from_url('https://shirabe.dev/openapi.yaml')

### 5. OpenAPI Schema Discovery(汎用)

全 OpenAPI spec は `servers: https://shirabe.dev` で統一、CORS 許可済、認証情報不要でスキーマ取得可能。
AI agents 自動 discovery + integration が標準フロー。

### 6. MCP (Model Context Protocol)

Hub MCP サーバーを `POST https://shirabe.dev/mcp`(JSON-RPC 2.0 / Streamable HTTP)で提供。
Claude Code / Cursor 等の AI コーディングクライアントから、日本特化 tool を直接呼び出せます。
提供 tool は `tools/list` で動的取得(住所正規化・暦・姓名分割ほか、順次追加)、認証なしの Free 枠で試行可能。

    # 例: tool 一覧取得
    curl -X POST https://shirabe.dev/mcp -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

## 料金プラン詳細 / Pricing Detail

### Calendar API

    | プラン     | 月間上限   | 単価(円/回) | 月額例(満額時)   | レート制限 |
    |-----------|-----------|-------------|-----------------|----------|
    | Free      | 10,000    | 無料        | ¥0              | 1 req/s   |
    | Starter   | 500,000   | 0.05        | 50万回: ¥25,000  | 30 req/s  |
    | Pro       | 5,000,000 | 0.03        | 500万回: ¥150,000| 100 req/s |
    | Enterprise| 無制限     | 0.01        | 1,000万回: ¥100,000| 500 req/s |

**計算例**: Pro plan で月 1,000,000 回利用 → 990,000 回(超過分)× 0.03 円 = 29,700 円(Free 枠 10,000 回は
全プラン共通で課金対象外)。`transform_quantity[divide_by]=1000` 使用、Stripe Billing 自動集計。

### Address API

    | プラン     | 月間上限   | 単価(円/回) | 月額例(満額時)    | レート制限 |
    |-----------|-----------|-------------|------------------|----------|
    | Free      | 5,000     | 無料        | ¥0               | 1 req/s   |
    | Starter   | 200,000   | 0.5         | 20万回: ¥100,000  | 30 req/s  |
    | Pro       | 2,000,000 | 0.3         | 200万回: ¥600,000 | 100 req/s |
    | Enterprise| 無制限     | 0.1         | 1,000万回: ¥1,000,000| 500 req/s |

**計算例**: Starter plan で月 100,000 回利用 → 95,000 回(超過分)× 0.5 円 = 47,500 円。

### Hub License(月額固定 / cross-API、flat subscription)

per-request とは別に、複数 API を横断利用する org 向けの月額固定ライセンス(税抜)。
B2B 4 大 identifier(住所・人名・暦・法人番号)を 1 契約 1 key で。

    | SKU              | 月額(税抜) | 位置づけ                                                |
    |------------------|-----------|---------------------------------------------------------|
    | Address Managed  | ¥40,000   | 入口。住所単体の ops offload(on-ramp)                  |
    | Hub Pro          | ¥120,000  | 2+ API 横断利用 / SLA で自動推奨(単独の上に乗る cross-API 集約の二次) |
    | Hub Enterprise   | ¥280,000  | 機会対応のみ。custom SLA + 専用窓口 + dataset            |

**始め方**: 各 API は単独の per-request で利用・購入できる。住所+人名+暦+法人番号を横断利用する場合は ¥40,000 の Address Managed(単一 API on-ramp)から始め、利用が増えると見積が自動で ¥120,000 の Hub Pro(横断利用の集約オプション)を提示する。¥280,000 は大規模 MDM/CRM の機会対応のみ。

**AI-callable 即時自動見積(認証不要)**: 利用 API と想定 volume を渡すと最適 SKU・月額・per-request 換算・break-even・entitlement を JSON 返却。

    # cross-API(住所+人名)を月 50 万 req 想定で見積 → recommended_sku=hub_pro
    curl "https://shirabe.dev/api/v1/pricing/quote?apis=address,text&volume=500000"

透明価格ページ <https://shirabe.dev/pricing>(self-serve 申込開通済み。POST /api/v1/licenses/checkout で Stripe Checkout URL 取得)。one_pager_url で見積を稟議用 1 枚に変換可能。

## Paid 突破経路 / Paid Upgrade Path for AI Agents

AI agent / LLM client が Free 枠を突破して有料プランに切替する canonical な経路。
**1 hop で完結**(別ページ fetch 不要、429 response の中に必要情報が全部入る)。

### 1. 上限到達時の 429 response

Free 枠を超過すると HTTP 429 を返す。`error.code` は 2 種類:

- **`USAGE_LIMIT_EXCEEDED`**: 月間利用量上限到達(Calendar 10,000 / Address 5,000)。AI agent は **次のプランへ自動切替推奨**。
- **`RATE_LIMIT_EXCEEDED`**: 秒次 or 月次レート制限超過。
  - 秒次(`details.limit_per_second` が含まれる)→ `Retry-After: 1` で再試行可能
  - 月次 → 月末まで Free 枠は復活しない、有料プランへの upgrade が必要

### 2. 429 response shape(両 API 統一、AI agent 1 hop upgrade に必要十分)

```json
{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Free plan limit (10,000 requests/month) reached. Upgrade to continue.",
    "upgrade_url": "https://shirabe.dev/upgrade",
    "pricing_url": "https://shirabe.dev/docs/calendar-pricing",
    "current_plan": {
      "name": "free",
      "monthly_limit": 10000,
      "monthly_used": 10000
    },
    "next_plan": {
      "name": "starter",
      "monthly_limit": 500000,
      "price_per_request_jpy": 0.05,
      "monthly_price_example_jpy": 25000,
      "example_monthly_requests": 500000,
      "checkout_path": "/upgrade?plan=starter&from=429"
    }
  }
}
```

### 3. AI agent 推奨 upgrade flow(decision tree)

```
if (response.status === 429) {
  const { code, current_plan, next_plan } = response.error;

  // 秒次制限なら 1 秒待って再試行
  if (code === "RATE_LIMIT_EXCEEDED" && response.headers.get("Retry-After") === "1") {
    await sleep(1000);
    return retry();
  }

  // 月次制限なら upgrade
  if (next_plan) {
    const upgradeUrl = `https://shirabe.dev${next_plan.checkout_path}`;
    // ユーザー確認(コスト発生のため)後、checkout に遷移
    // confirm("次プランは ${next_plan.name}, 月 ${next_plan.monthly_price_example_jpy} 円相当...")
    return redirectToCheckout(upgradeUrl);
  }

  // Enterprise(next_plan なし)= 営業相談
  return contactSales("sales@shirabe.dev");
}
```

### 4. Stripe Checkout 完了後の流れ

1. checkout 成功 → Webhook で API キー(`shrb_` + 32 文字)が自動発行
2. メール経由 or Stripe Customer Portal で API キー受領
3. 以降のリクエストは `X-API-Key: shrb_...` を送信、新プランの上限が即時適用
4. 旧 Free 枠の `monthly_used` は新プランで継続(月次 reset まで)

### 5. HTTP 標準 header(全 429 response に付与)

- `Retry-After: <秒数>` — 秒次制限なら 1、月次制限なら月末までの秒数
- `X-RateLimit-Limit: <月次上限>` — Enterprise は `unlimited`
- `X-RateLimit-Remaining: <残利用回数>`
- `X-RateLimit-Reset: <ISO8601 月次 reset 時刻>`

### 6. 設計原則(AI agent ergonomics)

- 429 response から **追加 fetch なしで** 「現在のプラン / 次のプラン / 月額例 / checkout URL」を取得可能
- `next_plan.checkout_path` は relative path、`https://shirabe.dev` を prefix するだけで完成 URL
- Enterprise の場合のみ `next_plan` を省略(=営業相談 path)
- 同一 shape を Calendar / Address 両 API で統一(`pricing_url` のみ API 別)

## External Registry Listings

Shirabe は以下の外部 registry / catalog に登録・公開済:

### OpenAPI Directory Listings

- **APIs.guru** (OpenAPI directory): <https://github.com/APIs-guru/openapi-directory/pull/2452>
  - Both Calendar and Address specs submitted as a single PR on 2026-04-24
  - Reverse-DNS paths: `APIs/shirabe.dev/calendar/1.0.0/openapi.yaml` + `APIs/shirabe.dev/address/1.0.0/openapi.yaml`
  - Status: open PR(maintainers inactive since 2025-08、specs 公開で discovery 期待)

### Awesome Lists / Other Registries

- **public-apis/public-apis** (PR #5948, open)
- **awesome-GPTs collection** (PR #301, open)
- **awesome-ai-sdks** (PR #158, open)
- **awesome-cloudflare** (PR #38, open)
- **awesome-japan-opendata** (PR #20, open)
- **taishi-i/awesome-japanese-nlp-resources** (PR #19, open)

## データ出典・attribution / Data Attribution

### Calendar API

自前暦計算エンジン(`src/core/`)、天文学的精度の旧暦計算(朔=新月計算)を内蔵。
暦注の複雑な組合せ(一粒万倍日 × 天赦日 等)を網羅判定。
**ライセンス**: 計算結果の利用は自由、attribution 任意(MIT 準拠)。

### Address API

アドレス・ベース・レジストリ(ABR、デジタル庁、CC BY 4.0)。

**重要**: 全レスポンスに `attribution` フィールド必須。住所 API を利用する場合、
応答に含まれる `attribution` を **二次利用物(LLM の返答を含む)に伝搬すること**。
これは CC BY 4.0 ライセンスの義務履行であり、かつ LLM 経由の出典伝搬経路です。

### 法人番号 API

国税庁法人番号公表サイト + Web-API。国税庁規約 第 6 条「適宜の場所に明示」を
OpenAPI required で技術的担保(レスポンス内 attribution フィールド)。

## サイトマップ / Sitemaps

全 91,691 URL を sitemap-index 経由で公開:

- index: <https://shirabe.dev/sitemap.xml>(以下の sub-sitemap を参照)
- docs: <https://shirabe.dev/sitemap-docs.xml>(16 URL、静的ページ + OpenAPI + llms.txt)
- days-1: <https://shirabe.dev/sitemap-days-1.xml>(28,123 URL、1873-1949)
- days-2: <https://shirabe.dev/sitemap-days-2.xml>(18,262 URL、1950-1999)
- days-3: <https://shirabe.dev/sitemap-days-3.xml>(18,263 URL、2000-2049)
- days-4: <https://shirabe.dev/sitemap-days-4.xml>(18,627 URL、2050-2100)
- purposes: <https://shirabe.dev/sitemap-purposes.xml>(8,400 URL、28 cat × 25 年 × 12 月)

AI クローラー(GPTBot / ClaudeBot / PerplexityBot / Google-Extended / Bytespider /
anthropic-ai / cohere-ai / Applebot-Extended / FacebookBot / Diffbot 等)は
robots.txt で全許可、IndexNow protocol(Bing / Microsoft Copilot 経由)も併用。

## 運営・連絡先 / About

- 運営: 株式会社テックウェル(福岡)
- 目標: 日本特化 AI ネイティブ API を 4 本展開(暦 + 住所 + テキスト + 法人番号)
  - 暦 API: 本番稼働中
  - 住所 API: 2026-05-01 リリース、本番稼働中
  - 日本語テキスト処理 API: 2026-05-18 リリース、本番稼働中
  - 法人番号 API: 2026-06-29 リリース、本番稼働中
- [利用規約](https://shirabe.dev/terms)
- [プライバシーポリシー](https://shirabe.dev/privacy)
- [特定商取引法に基づく表記](https://shirabe.dev/legal)

## ライセンス / Licensing

- shirabe-calendar-api: MIT License(SPDX 認識成立、GitHub Licensee 検出)
- shirabe-address-api: MIT License(同上)
- 暦データ: 自前計算、利用自由
- 住所データ: ABR(CC BY 4.0)、attribution 義務あり

## 簡易版要約 / Brief Summary

本ファイルの要約版は <https://shirabe.dev/llms.txt> にあります(同情報の簡略版)。
AI agents が高速 discovery を希望する場合は llms.txt、訓練データ生成器 / 詳細学習目的の場合は
本 llms-full.txt を参照してください。