埋め込みウィジェット

ウェブサイト用の埋め込みウィジェットを作成・管理します。ウィジェットは、1つの占星術機能をそのまま使えるUIコンポーネントにしたものです。出生データフォーム、月カレンダー、日別ホロスコープの星座セレクターなどがあります。ダッシュボードまたはこのAPIで設定し、スクリプトタグ1つで任意のページに配置できます。

2つのAPI、2つのキー

管理API（/api/widgets）はウィジェットの作成と設定を行います。通常のAPIキーを使用します。
ウィジェットAPI（/api/widget-api）は、訪問者のブラウザからSDKが呼び出すAPIです。ウィジェット専用のキーを使用します。このキーは対象のウィジェット1つに限定されるため、ページに記述しても安全です。

ノーコードの手順をお探しですか？ウェブサイトへのウィジェットの追加をご覧ください。

ウィジェットタイプ

作成できるウィジェットタイプは、組織で有効になっているモジュールによって決まります。GET /api/widgets/options で利用可能なタイプを一覧できます。

タイプ	説明	必要なモジュール
`natal`	出生データフォームとチャート、天体位置、アスペクト	`module:natal`
`synastry`	2人分の出生データフォーム、シナストリーチャート、相互アスペクト	`module:natal`, `module:synastry`
`transit`	出生データとトランジット時刻、バイホイールチャート	`module:natal`, `module:transits`
`composite`	2人分の出生データフォーム、コンポジットチャート	`module:natal`, `module:composite`
`moonphase`	現在の月相と輝面比	`module:moon`
`daily-horoscope`	星座セレクターと本日のホロスコープ	`module:daily-report`
`numerology`	氏名と生年月日のフォーム、コアナンバー	`module:numerology`
`compatibility`	2人分の入力と数秘術による相性スコア	`module:numerology`, `module:compatibility`
`moon-calendar`	月相・月の出・月の入りを含む月間カレンダー	`module:moon`

ウィジェット管理

すべての管理エンドポイントはJSON:API形式で、リソースタイプは widget です。

ウィジェットの一覧

bash

curl "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key"

ウィジェットの取得

bash

curl "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

ウィジェットの作成

bash

curl -X POST "https://api.astroapi.cloud/api/widgets" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "widget",
      "attributes": {
        "name": "My Natal Chart Widget",
        "widgetType": "natal",
        "allowedDomains": ["example.com", "www.example.com"],
        "customization": {
          "language": "en",
          "layout": { "variant": "card" },
          "colors": {
            "primary": "#5b2d8e",
            "background": "#ffffff",
            "text": "#1a1a1a"
          },
          "widgetOptions": {
            "showAspects": true,
            "showPoints": true,
            "showHouses": true,
            "chartSize": "medium",
            "theme": "auto"
          }
        }
      }
    }
  }'

完全なウィジェットAPIキー（apiKey）が返されるのは、作成時のレスポンスだけです。必ず保存しておくか、後で再生成してください。それ以外のレスポンスには apiKeyPrefix しか含まれません。

json

{
    "data": {
        "type": "widget",
        "id": "wgt_abc123",
        "attributes": {
            "name": "My Natal Chart Widget",
            "widgetType": "natal",
            "customization": { "...": "as sent, merged with defaults when served" },
            "allowedDomains": ["example.com", "www.example.com"],
            "enabled": true,
            "createdAt": "2026-06-15T12:00:00.000Z",
            "updatedAt": "2026-06-15T12:00:00.000Z",
            "apiKey": "wk_live_...",
            "apiKeyPrefix": "wk_live_abc1"
        },
        "relationships": {
            "organization": { "data": { "type": "organization", "id": "org_..." } }
        }
    }
}

ウィジェットの更新

PATCH は name、enabled、allowedDomains、customization の任意の組み合わせを受け付けます。カスタマイズはオブジェクト全体が置き換えられるため、完全なオブジェクトを送信してください。

bash

curl -X PATCH "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "type": "widget",
      "id": "wgt_abc123",
      "attributes": {
        "name": "Updated Widget Name",
        "customization": { "language": "nl" }
      }
    }
  }'

ウィジェットの削除

bash

curl -X DELETE "https://api.astroapi.cloud/api/widgets/wgt_abc123" \
  -H "X-Api-Key: your-api-key"

ウィジェットAPIキーの再生成

bash

curl -X POST "https://api.astroapi.cloud/api/widgets/wgt_abc123/regenerate-key" \
  -H "X-Api-Key: your-api-key"

新しい apiKey を持つウィジェットが返されます。サイトの埋め込みコードを新しいキーで更新してください。ウィジェットIDは変わりません。

利用可能なウィジェットオプション

bash

curl "https://api.astroapi.cloud/api/widgets/options" \
  -H "X-Api-Key: your-api-key"

json

{
    "data": {
        "type": "widget-options",
        "id": "org_...",
        "attributes": {
            "plan": "Gold",
            "organizationModules": ["module:natal", "module:moon"],
            "availableWidgetTypes": ["natal", "moonphase", "moon-calendar"],
            "features": {
                "canRemoveBranding": false,
                "canUseCustomLogo": false,
                "canUseCustomCss": false,
                "maxDomains": 5
            },
            "allWidgetTypes": [
                {
                    "id": "natal",
                    "name": "Natal Chart",
                    "requiredModules": ["module:natal"],
                    "displayOptions": { "showChartSize": true, "showAspects": true, "showPoints": true }
                }
            ]
        }
    }
}

プラン機能

機能	説明
`canRemoveBranding`	`branding.showPoweredBy` に `false` を設定できます
`canUseCustomLogo`	`branding.logoUrl` と `branding.companyName` を設定できます
`canUseCustomCss`	`customCss` がウィジェットに配信されます
`maxDomains`	ウィジェットあたりの `allowedDomains` の最大数、または `"unlimited"`

カスタマイズオブジェクト

すべてのフィールドは任意です。省略した項目は、ウィジェットの配信時に以下のデフォルト値で補完されます。色はCSSのカラー文字列、サイズはピクセル単位の数値です。

json

{
    "colors": {
        "primary": "#6366f1",
        "secondary": "#8b5cf6",
        "background": "#ffffff",
        "surface": "#f8fafc",
        "text": "#1e293b",
        "textSecondary": "#64748b",
        "border": "#e2e8f0",
        "error": "#ef4444",
        "success": "#22c55e",
        "accent": "#f59e0b"
    },
    "fonts": {
        "family": "Inter, system-ui, sans-serif",
        "sizeBase": 16,
        "sizeHeading": 24,
        "sizeSmall": 12,
        "weightNormal": 400,
        "weightBold": 600
    },
    "borders": { "radius": 8, "width": 1, "style": "solid" },
    "spacing": { "padding": 16, "margin": 16 },
    "shadows": { "preset": "sm", "custom": null },
    "layout": { "variant": "card" },
    "interaction": {
        "tooltipEnabled": true,
        "animationsEnabled": true,
        "clickThroughEnabled": false,
        "clickThroughUrl": null
    },
    "chartSettings": {},
    "labels": {},
    "language": "en",
    "branding": { "showPoweredBy": true, "logoUrl": null, "companyName": null },
    "customCss": null,
    "widgetOptions": {
        "showAspects": true,
        "showPoints": true,
        "showHouses": true,
        "chartSize": "medium",
        "theme": "light"
    },
    "numerologyOptions": {
        "showLifePath": true,
        "showExpression": true,
        "showSoulUrge": true,
        "showPersonality": true,
        "showBirthday": true,
        "showPersonalCycles": true
    },
    "dailyHoroscopeOptions": { "autoRefresh": false },
    "moonCalendarOptions": {
        "showMoonrise": true,
        "showMoonset": true,
        "showIllumination": true,
        "showPhaseEmoji": true,
        "highlightFullMoon": true,
        "highlightNewMoon": true
    },
    "compatibilityOptions": {
        "showScore": true,
        "showDescription": true,
        "showLifePaths": true
    }
}

カスタマイズフィールド

フィールド	型	説明
`colors.*`	string	10種類のCSSカラー。ウィジェット上でCSS変数として適用されます
`fonts.family`	string	CSSの `font-family` 値
`fonts.sizeBase` / `sizeHeading` / `sizeSmall`	number	フォントサイズ（ピクセル）
`fonts.weightNormal` / `weightBold`	number	フォントウェイト
`borders.radius` / `width`	number	ピクセル単位。入力欄、ボタン、カードレイアウトで使用されます
`borders.style`	string	`solid`、`dashed`、`dotted`、`none`
`spacing.padding` / `margin`	number	ピクセル単位。カードレイアウトとコンパクトレイアウトは `padding` を使用します
`shadows.preset`	string	`none`、`sm`、`md`、`lg`、`xl`（カードレイアウト）
`shadows.custom`	string \| null	プリセットを上書きするCSSの `box-shadow`
`layout.variant`	string	レイアウトバリアントを参照
`interaction.tooltipEnabled`	boolean	天体の行、アスペクトの行、カレンダーの日付に表示されるホバーツールチップ
`interaction.animationsEnabled`	boolean	表示時のアニメーション。動きを減らす設定の訪問者には常に無効です
`interaction.clickThroughEnabled`	boolean	描画されたチャートを `clickThroughUrl` へのリンクにします
`interaction.clickThroughUrl`	string \| null	新しいタブで開きます
`chartSettings`	object	デフォルトのチャートテーマに重ねてマージされる部分的なチャートテーマ。サイン・天体・アスペクトごとの色、線幅、`showDegrees`、`showRetrograde` などを指定します
`labels`	object	任意のラベルキーの上書き。言語とラベルを参照
`language`	string	サポートされている13の言語コードのいずれか
`branding.showPoweredBy`	boolean	`false` にするには `canRemoveBranding` が必要です
`branding.logoUrl` / `companyName`	string \| null	`canUseCustomLogo` が必要です
`customCss`	string \| null	ウィジェット用にページへ挿入されます。`canUseCustomCss` が必要です
`widgetOptions.showAspects` / `showPoints`	boolean	チャートの下にアスペクト表と天体位置表を表示します
`widgetOptions.showHouses`	boolean	チャートにハウス番号を表示します
`widgetOptions.chartSize`	string \| number	`small`（300）、`medium`（450）、`large`（600）、またはピクセル単位の幅
`widgetOptions.theme`	string	`light`、`dark`、`cosmic`、`custom`、`auto`
`numerologyOptions.*`	boolean	数秘術ウィジェットに表示する数値
`dailyHoroscopeOptions.autoRefresh`	boolean	予約済み
`moonCalendarOptions.*`	boolean	カレンダーの各日に表示する情報と、強調表示する月相
`compatibilityOptions.*`	boolean	スコアのリング表示、説明文、ライフパスナンバー

レイアウトバリアント

値	説明
`card`	設定した角丸・パディング・影を持つ枠付きの面（デフォルト）
`compact`	パディングを半分にし、文字をやや小さくします。サイドバー向けです
`full`	左右いっぱいに広がり、パディングは上下のみです
`minimal`	枠は一切なく、すべてをページから継承します

テーマ

light、dark、cosmic は、面と枠線の色が固定されたパレットです。auto はライトパレットを使用し、訪問者のシステムがダークを優先している場合にダークパレットへ切り替わります。custom は何も設定せず、指定した colors だけに従います。どのテーマでも、設定した10個の colors がパレットより優先されます。

言語とラベル

SDKには en、nl、de、fr、es、es-419、it、pt、pt-BR、tr、ru、ja、zh-CN のラベルが同梱されています。地域バリアントは、独自に上書きしていない項目についてはベース言語にフォールバックします。labels は、選択した言語の上から個々の文字列を上書きします。例：

json

{ "language": "nl", "labels": { "calculateButton": "Bereken mijn horoscoop" } }

言語はページ単位で設定することもできます。スクリプトタグの data-lang="de"、またはページURLの ?lang=de は、いずれも保存された言語より優先されます。

ウィジェットの埋め込み

SDKは https://widgets.astroapi.cloud/sdk.js から配信されます。ダッシュボードの 埋め込み タブでは、以下の2つのスニペットがご自身のIDを埋め込んだ状態で生成されます。

自動初期化

html

<script
  src="https://widgets.astroapi.cloud/sdk.js"
  data-widget-id="wgt_abc123"
  data-api-key="your-widget-api-key"
  data-api-url="https://api.astroapi.cloud"
></script>
<div id="astro-widget-wgt_abc123"></div>

任意の属性：デフォルトの div 以外の場所に描画するには data-container="#my-element"、言語を上書きするには data-lang="nl" を指定します。

プログラムからの初期化

html

<script src="https://widgets.astroapi.cloud/sdk.js"></script>
<div id="my-widget"></div>
<script>
  AstroWidget.create({
    widgetId: "wgt_abc123",
    apiKey: "your-widget-api-key",
    apiBaseUrl: "https://api.astroapi.cloud",
    container: "#my-widget",
    language: "nl",
    defaultValues: {
      dateTime: "1990-06-15T14:30:00",
      latitude: 52.3676,
      longitude: 4.9041,
      timezone: "Europe/Amsterdam",
      placeName: "Amsterdam"
    },
    onLoad: () => console.log("Widget loaded"),
    onResult: (result) => console.log("Result", result),
    onError: (err) => console.error(err)
  }).then((widget) => {
    // widget.type, widget.getResult(), widget.setBirthData(), widget.calculate(), widget.destroy()
  });
</script>

defaultValues.dateTime は timezone におけるローカル時刻として解釈され、フォームには指定したとおりに表示されます。

インスタンスAPI

メンバー	説明
`id`, `type`	ウィジェットIDとウィジェットタイプ
`getResult()`	最新の結果。訪問者が計算したものか `calculate()` が計算したものかを問いません
`setBirthData(data)`	`calculate()` が使用する出生データ
`calculate()`	スクリプトから計算を実行し、結果を表示します。`natal`、`transit`（現在時刻）、`moonphase`、`moon-calendar`（当月）に対応しています。それ以外のタイプは訪問者の入力を前提とするため、エラーでリジェクトされます
`destroy()`	ウィジェットをアンマウントします

onResult は、すべてのウィジェットタイプで、ウィジェットが結果を表示するたびに発火します。AstroWidget.version はSDKのビルドを返します。

ドメイン

allowedDomains は、ウィジェットAPIキーが有効に機能する場所を制限するもので、ブラウザからのリクエストの Origin と照合されます。サブドメインのワイルドカード（*.example.com）に対応しており、www. はベースドメインと同じものとして扱われます。リストが空の場合はキーがどのドメインでも機能してしまうため、埋め込みコードを公開する前に必ず設定してください。

ウィジェットAPI

以下は、SDKが訪問者に代わって呼び出すエンドポイントです。ウィジェットに対して独自のフロントエンドを構築できるように掲載しています。リファレンス実装はSDKです。

認証は X-Api-Key に指定するウィジェットAPIキーで行います。ダッシュボードのプレビューでは、代わりにセッションを使用します。

エンドポイント	ボディ	ウィジェットタイプ
`GET /api/widget-api/config/:widgetId`	—	すべて。公開エンドポイントで、`widgetType` とマージ済みの `customization` を返します
`POST /api/widget-api/natal/:widgetId`	`{ birthData }`	`natal`
`POST /api/widget-api/synastry/:widgetId`	`{ person1, person2 }`	`synastry`
`POST /api/widget-api/transit/:widgetId`	`{ birthData, transitDateTime, transitTimezone? }`	`transit`
`POST /api/widget-api/composite/:widgetId`	`{ person1, person2 }`	`composite`
`POST /api/widget-api/moonphase/:widgetId`	`{ date?, latitude? }`	`moonphase`
`POST /api/widget-api/daily-horoscope/:widgetId`	`{ zodiacSign, date? }`	`daily-horoscope`
`POST /api/widget-api/numerology/:widgetId`	`{ fullName, birthYear, birthMonth, birthDay }`	`numerology`
`POST /api/widget-api/compatibility/:widgetId`	`{ person1, person2 }`（氏名と生年月日の各要素）	`compatibility`
`POST /api/widget-api/moon-calendar/:widgetId`	`{ year, month, latitude?, longitude?, timezone? }`	`moon-calendar`
`GET /api/widget-api/geocoding/search/:widgetId?q=&limit=&lang=`	—	すべて。出生データフォーム用の地名検索

チャート系ウィジェットの birthData、person1、person2 は { dateTime, latitude, longitude, timezone, placeName? } で、dateTime は timezone におけるローカル時刻（1990-06-15T14:30:00）です。別のタイプのウィジェットに対してエンドポイントを呼び出すと 400 が返ります。無効化されたウィジェットは 403、allowedDomains に含まれないドメインからのリクエストは 403 DOMAIN_NOT_ALLOWED を返します。

次のステップ

ウェブサイトへのウィジェットの追加 — WordPress、Wix、Squarespace、Shopify、Webflowの手順
チャートレンダリング — chartSettings が受け付けるテーマオブジェクト
AIチャットボット — チャットボットには専用の埋め込みウィジェットがあります

埋め込みウィジェット ​

ウィジェットタイプ ​

ウィジェット管理 ​

ウィジェットの一覧 ​

ウィジェットの取得 ​

ウィジェットの作成 ​

ウィジェットの更新 ​

ウィジェットの削除 ​

ウィジェットAPIキーの再生成 ​

利用可能なウィジェットオプション ​

プラン機能 ​

カスタマイズオブジェクト ​

カスタマイズフィールド ​

レイアウトバリアント ​

テーマ ​

言語とラベル ​

ウィジェットの埋め込み ​

自動初期化 ​

プログラムからの初期化 ​

インスタンスAPI ​

ドメイン ​

ウィジェットAPI ​

次のステップ ​

埋め込みウィジェット

ウィジェットタイプ

ウィジェット管理

ウィジェットの一覧

ウィジェットの取得

ウィジェットの作成

ウィジェットの更新

ウィジェットの削除

ウィジェットAPIキーの再生成

利用可能なウィジェットオプション

プラン機能

カスタマイズオブジェクト

カスタマイズフィールド

レイアウトバリアント

テーマ

言語とラベル

ウィジェットの埋め込み

自動初期化

プログラムからの初期化

インスタンスAPI

ドメイン

ウィジェットAPI

次のステップ