# ジオスタジオ 詳細マニュアル | 設定リファレンス・トラブルシューティング - KINTAUROS

> kintoneプラグイン「ジオスタジオ」の詳細マニュアル。全設定項目のリファレンス(意味・制約値)、動作条件・制限事項、エラーコード別のトラブルシューティングを掲載。対象バージョン: v1.3.1。

元ページ: https://kintauros.com/plugins/geo-studio/manual/

ジオスタジオは、カスタマイズビュー1枚を、地図ビュー(ピンマップ/都道府県色分けマップ)のタブ切替にするプラグインです。緯度・経度を持つレコードを地図上のピンや統計バブルで、都道府県名・住所を持つレコードを都道府県の塗り分けマップで表示できます。住所しかないアプリのために、設定画面から住所→緯度・経度の一括変換(ジオコーディング)もできます。このマニュアルでは、設定項目のリファレンスと、動作仕様・制限事項・トラブルシューティングを説明します。

機能紹介・画面イメージ・導入手順は[プラグイン紹介ページ](https://kintauros.com/plugins/geo-studio/)を、ダウンロードは[ダウンロードページ](https://kintauros.com/download/)をご覧ください。このマニュアルは[Markdown版](index.md)でも提供しており、全プラグインのメタ情報と設定スキーマは機械可読な[catalog.json](https://kintauros.com/catalog.json)から取得できます。

## 基本情報

- **プラグインID**: geo-studio

- **対象バージョン**: v1.3.1(配布中の最新版)

- **カテゴリ**: 一覧画面カスタマイズ

- **説明**: レコードの緯度経度や住所を、地図のピン表示と都道府県の色分けマップで可視化します。

## 動作条件

- **対応環境**: kintone スタンダードコース(デスクトップ版UI)。最新版の Chrome / Edge / Safari / Firefox に対応。

- **動作画面**: レコード一覧のカスタマイズビュー。指定したビューを開くとタブ切替の地図ビューが表示されます。

- **必要なフィールド**: タイトルフィールド(ポップアップ等の見出し)のほか、使うビューに応じて: ピンマップ=緯度・経度の数値・計算または文字列(1行)×2、都道府県マップ=都道府県名または住所の文字列(1行)・ドロップダウン・ラジオボタン。ピンの色分けはドロップダウンまたはラジオボタン、統計バブルのサイズ基準・合計・平均の集計値には数値または計算フィールドを使います。

- **必要な権限**: 閲覧はレコード閲覧権限。一括ジオコーディングの実行(設定画面)にはアプリ管理権限と対象レコードの編集権限が必要です。

## 設定項目リファレンス

プラグイン設定の全項目です。「項目」は設定データ(エクスポートファイルの config)のキーを表し、[] は配列の要素を意味します。設定画面での入力項目と1対1に対応します。この構造の正式な定義はJSON Schema([catalog.json](https://kintauros.com/catalog.json) の configSchema)として公開しています。

- **項目**: 型 / 必須 / 説明・制約

- **targetView**: 文字列 / 必須 / 対象ビューのID / ジオスタジオを表示するカスタマイズビューのビューID(数値文字列)。ビュー名ではない。 / 1文字以上

- **titleField**: 文字列 / 必須 / タイトルフィールド(全ビュー共有) / ピンのポップアップなどで見出しとして表示するフィールドのフィールドコード。 / 1文字以上 / 対応フィールド型: SINGLE_LINE_TEXT, NUMBER, CALC, DROP_DOWN, RADIO_BUTTON, LINK

- **detailSpaceId**: 文字列 / 任意 / 詳細画面の地図スペースID(任意) / レコード詳細画面のスペース要素の要素IDを指定すると、そのレコードの位置を示す小さな地図(先頭のピンマップの緯度・経度フィールドを使用)をそこに表示する。空なら表示しない。

- **views**: 配列 / 必須 / ビュー(タブ) / タブとして並ぶビューの定義。配列の順序がタブの並び順(先頭が初期表示)。タイプに応じて pins / prefecture のいずれかの設定を持つ。 / 1件以上 / 5件以内

- **views[].name**: 文字列 / 必須 / ビュー名 / タブに表示する名前。 / 1文字以上 / 40文字以内

- **views[].type**: 文字列 / 必須 / ビュータイプ / pins=緯度経度のピンマップ / prefecture=都道府県の色分けマップ。 / 値: pins | prefecture

- **views[].pins**: オブジェクト / 任意 / ピンマップの設定(type=pins のとき必須)

- **views[].pins.latField**: 文字列 / 任意 / 緯度フィールド / 緯度(10進数。例 35.6812)を保持する数値・計算または文字列(1行)フィールドのフィールドコード。 / 1文字以上 / 対応フィールド型: NUMBER, CALC, SINGLE_LINE_TEXT

- **views[].pins.lngField**: 文字列 / 任意 / 経度フィールド / 経度(10進数。例 139.7671)を保持する数値・計算または文字列(1行)フィールドのフィールドコード。 / 1文字以上 / 対応フィールド型: NUMBER, CALC, SINGLE_LINE_TEXT

- **views[].pins.cardFields**: 配列(文字列) / 任意 / ポップアップに表示するフィールド / ピンをクリックしたときにタイトルの下に表示する追加フィールド。0〜4個。 / 4件以内 / 1文字以上

- **views[].pins.detailFields**: 配列(文字列) / 任意 / 詳細情報に表示するフィールド / ポップアップの「詳細を見る」で地図の左側に開く詳細パネルに、ポップアップのフィールドの下に表示する追加フィールド。0〜10個。リンクフィールドはリンクとして表示。 / 10件以内 / 1文字以上

- **views[].pins.imageField**: 文字列 / 任意 / アイキャッチ画像フィールド / 詳細パネルの先頭に表示する添付ファイルフィールドのフィールドコード(画像のみ表示。複数あればカルーセル)。空なら表示しない。 / 対応フィールド型: FILE

- **views[].pins.colorField**: 文字列 / 任意 / 色分け基準フィールド / ドロップダウンまたはラジオボタンのフィールドコード。colors の色でピンを色分けする。空なら色分けしない。 / 対応フィールド型: DROP_DOWN, RADIO_BUTTON

- **views[].pins.colors**: オブジェクト / 任意 / 色分けの色 / キーは色分け基準フィールドの選択肢ラベル、値は色(#RRGGBB)。

- **views[].pins.marker**: 文字列 / 任意 / 表示方法 / pin=ピン(既定) / bubble=統計バブル(sizeField の値に応じた大きさの円。面積が値に比例)。 / 値: pin | bubble

- **views[].pins.sizeField**: 文字列 / 任意 / 統計バブルのサイズ基準フィールド / 数値・計算フィールドのフィールドコード。marker=bubble のとき必須。 / 対応フィールド型: NUMBER, CALC

- **views[].pins.maxRadius**: 整数 / 任意 / 統計バブルの最大半径(px) / 最大値のレコードの円の半径。既定は30。 / 10以上 / 80以下

- **views[].pins.opacity**: 数値 / 任意 / 統計バブルの不透明度 / 円の塗りの不透明度(0.1〜1)。重なりが見にくいときに下げる。既定は0.6。 / 0.1以上 / 1以下

- **views[].prefecture**: オブジェクト / 任意 / 都道府県色分けマップの設定(type=prefecture のとき必須) / 同梱の都道府県ポリゴンをレコードの集計値で塗り分ける。地図タイルは使わず、外部リクエストは発生しない。

- **views[].prefecture.prefField**: 文字列 / 任意 / 都道府県フィールド / 都道府県名(例「東京都」「大阪府」。「東京」など接尾辞なしも可)または住所文字列(先頭の都道府県名を抽出)を保持するフィールドのフィールドコード。 / 1文字以上 / 対応フィールド型: SINGLE_LINE_TEXT, DROP_DOWN, RADIO_BUTTON

- **views[].prefecture.mode**: 文字列 / 任意 / 集計方法 / count=レコード件数 / sum=合計 / avg=平均(sum・avg は valueField 必須)。 / 値: count | sum | avg

- **views[].prefecture.valueField**: 文字列 / 任意 / 集計値フィールド / sum・avg の対象となる数値・計算フィールドのフィールドコード。mode=count のときは不要。 / 対応フィールド型: NUMBER, CALC

- **views[].prefecture.palette**: 文字列 / 任意 / 配色 / 塗り分けの配色(値の小→大の5段階)。blue=青(既定) / green=緑 / heat=赤 / purple=紫 / rdylgn=赤/黄/緑 / rdwb=赤/白/青。 / 値: blue | green | heat | purple | rdylgn | rdwb

- **views[].prefecture.paletteReverse**: 真偽値 / 任意 / 配色を反転する / true にすると値の小⇔大への色の割り当てを入れ替える。

- **geocode**: オブジェクト / 任意 / ジオコーディング(一括変換ツールの既定値) / 設定画面の「住所から緯度・経度を一括変換」で使うフィールドの割り当て。変換は設定画面から管理者が明示的に実行したときのみ行われ、そのとき住所文字列が国土地理院の住所検索APIへ直接送信される(KINTAUROSのサーバーは経由しない)。実行画面では一切送信されない。

- **geocode.addressField**: 文字列 / 任意 / 住所フィールド / 変換元の住所を保持する文字列(1行)フィールドのフィールドコード。 / 対応フィールド型: SINGLE_LINE_TEXT

- **geocode.latField**: 文字列 / 任意 / 緯度の保存先フィールド / 変換結果の緯度を保存する数値または文字列(1行)フィールドのフィールドコード。 / 対応フィールド型: NUMBER, SINGLE_LINE_TEXT

- **geocode.lngField**: 文字列 / 任意 / 経度の保存先フィールド / 変換結果の経度を保存する数値または文字列(1行)フィールドのフィールドコード。 / 対応フィールド型: NUMBER, SINGLE_LINE_TEXT

- **publish**: オブジェクト / 任意 / Web公開(KINTAUROS Publish)の設定。全対応プラグイン共通の断片で、共通ランタイム(KINTAUROS.publish)が読み書きする。tenantId / slug は公開サイト側の識別子で、別アプリへインポートしたときは引き継がれない

- **publish.enabled**: 真偽値 / 任意 / Web公開を有効にするか

- **publish.tenantId**: 文字列 / 任意 / 公開サイトのテナントID(「公開を開始」で発行)

- **publish.slug**: 文字列 / 任意 / 公開サイトのサブドメイン({slug}.kintauros.site)

- **publish.whitelist**: 配列(文字列) / 任意 / 公開するフィールドのコード。ここに無いフィールドは公開サイトへ保存されない

- **publish.attachments**: 配列(文字列) / 任意 / 公開する添付ファイルフィールドのコード(画像のみ転写される)

- **publish.condition**: オブジェクト / 任意 / 公開するレコードの条件(構造化)。always=全件 / in=フィールドの値が values のいずれか / not_empty=フィールドが空でない

- **publish.condition.operator**: 文字列 / 必須 / 値: always | in | not_empty

- **publish.condition.field**: 文字列 / 任意 / -

- **publish.condition.values**: 配列(文字列) / 任意 / -

- **publish.site**: オブジェクト / 任意 / -

- **publish.site.name**: 文字列 / 任意 / サイト名(公開ページのヘッダーに表示) / 100文字以内

- **publish.site.themeColor**: 文字列 / 任意 / 形式: ^#[0-9a-fA-F]{6}$

- **publish.site.noindex**: 真偽値 / 任意 / 検索エンジンに登録しない

- **publish.syncUsers**: 配列 / 任意 / 一覧・詳細画面に公開ボタンを表示するユーザー(空なら全員)

- **publish.syncUsers[].type**: 文字列 / 必須 / 値: user | group

- **publish.syncUsers[].code**: 文字列 / 必須 / -

- **publish.customDomain**: 文字列 / 任意 / 独自ドメイン(例: help.example.com)。設定画面の「このドメインを登録」で登録し、DNS の CNAME が有効になってから公開できる(無料お試し中も利用可)。空なら既定の {slug}.kintauros.site

## 設定のポイント

- targetView にはジオスタジオを表示するカスタマイズビューのビューIDを指定します。ビューのHTMLは空でかまいません。

- views(ビュー)は最大5個まで定義でき、配列の順序がタブの並び順、先頭のビューが初期表示になります。同じタイプのビューを軸や配色を変えて複数並べることもできます(例: 「顧客マップ」「売上バブル」)。設定画面のビューカードの複製ボタン(⧉)で、条件違いのビューを簡単に作れます。

- 緯度・経度は10進数(例: 緯度 35.6812 / 経度 139.7671)で保持してください。度分秒表記(35°40′52″など)は読み取れません。

- ピンマップの「表示方法」は ピン(既定) と 統計バブル から選べます。統計バブルはサイズ基準の数値フィールドが必須で、円の面積が値に比例します(最大半径 10〜80px・既定30 / 不透明度 0.1〜1・既定0.6)。

- 都道府県マップの都道府県フィールドは、都道府県名(「東京都」「大阪府」。「東京」など接尾辞なしも可)のほか、住所文字列でもかまいません(先頭の都道府県名を自動で抽出します)。

- 都道府県マップの配色は6種類(青・緑・赤・紫・赤/黄/緑・赤/白/青)+反転から選べます。「多いほど良い」指標は青や緑、「多いほど危険」な指標は赤、目標比のような中間に意味がある指標は赤/黄/緑などの分岐配色が向いています。

- 一括ジオコーディング(住所から緯度・経度を一括変換)は、住所・緯度・経度のフィールドを割り当てて設定画面から実行します。緯度・経度が両方入っているレコードはスキップされます(「変換済みも上書き」にチェックすると全件変換し直します)。

## 動作仕様

- レコードはビューを開いたときに一括取得し(500件ずつ・最大1万件)、全ビューで共有します。タブ切替時の再取得はありません(「再読み込み」ボタンで最新化できます)。

- ピンマップ: 緯度・経度が有効なレコードをピンで表示します。ピンをクリックすると、タイトルと設定したフィールド(最大4個)がポップアップし、レコード詳細へのリンクも表示されます。色分け基準フィールド(ドロップダウン/ラジオ)を設定すると、選択肢ごとの色でピンが塗り分けられ、凡例が表示されます。

- ピンマップの表示件数が1,500件を超えると、ピンの代わりに軽量な丸マーカー(canvas描画)に自動で切り替わります。

- 統計バブル: サイズ基準フィールドの値が正の数のレコードを、値に応じた大きさの円で表示します(面積が値に比例。大きい円から順に描画するため、小さい円が埋もれません)。値が0以下・未入力のレコードは表示されません。

- 都道府県マップ: 都道府県フィールドの値から都道府県を判定し、件数・合計・平均の集計値で5段階に塗り分けます。地図データはプラグインに同梱されており、外部リクエストなしで描画されます。都道府県にマウスを載せると集計値がポップアップします。

- 地図の拡大縮小は Ctrl(⌘)+ホイール、またはズームボタンで行います(ホイール単独はページスクロールを優先する誤操作防止の仕様です)。

- 一括ジオコーディング: 実行の都度、送信先(国土地理院の住所検索API)への同意チェックと確認ダイアログを挟んでから、1件/秒で変換します(サーバー負荷への配慮)。変換結果は四捨五入して小数第6位までを緯度・経度フィールドに保存します。「中断」ボタンでいつでも止められ、そこまでの結果は保存されます。

- 外部通信: レコードの内容が当社(KINTAUROS)のサーバーに送信されることはありません。ピンマップの地図タイル画像(国土地理院タイル)の取得時に表示領域のタイル座標が国土地理院に渡るのみで、ジオコーディングは設定画面から明示的に実行したときだけ住所文字列を国土地理院へ直接送信します。都道府県マップは外部リクエストなし。地図ライブラリ(Leaflet)は同梱です。

## 制限事項・既知の仕様

- モバイルアプリの画面では動作しません(デスクトップ版UIのみ)。

- 表示できるレコードは最大1万件です。超過分は表示されず、件数表示に「(上限)」と表示されます。

- ビューは5個まで、ポップアップに表示する追加フィールドは4個までです。

- 都道府県マップは日本の47都道府県のみ対応です。市区町村単位の塗り分けや海外の地図には対応していません。

- ジオコーディングの精度は国土地理院の住所検索APIに依存します(概ね番地精度が目安)。ビル名や旧住所を含む表記は見つからないことがあります。

- 地図タイルは国土地理院の淡色地図に固定です(タイル提供元の変更・カスタムタイルURLの指定はできません)。

## 設定のインポート / エクスポート

プラグイン設定画面の上部にある「設定のインポート / エクスポート」から、現在の設定をJSONファイルとして書き出し(エクスポート)、別のアプリで読み込み(インポート)できます。検証用アプリから本番アプリへの設定コピーや、バックアップ・復元にご利用ください。

- インポートは取り込む内容の差分を確認してから「設定画面に反映」し、最後に「保存」を押して確定します(反映しただけでは保存されません)。

- 読み込んだファイルはブラウザ内で処理され、KINTAUROSのサーバーには送信されません。

- 別のアプリの設定を取り込んだ場合、このアプリに存在しないフィールドは警告として一覧表示されるので、反映後に該当箇所を選び直してください。

エクスポートファイルは次の形式(封筒形式)です。config の中身が設定本体で、その構造は上の設定項目リファレンスのとおりです。

```
{
  "kintauros": "config/v1",
  "plugin": "<プラグインID>",
  "pluginName": "<プラグイン名>",
  "pluginVersion": "<バージョン>",
  "exportedAt": "<書き出し日時(ISO 8601)>",
  "sourceApp": "<書き出し元アプリID>",
  "config": { ... 設定本体 ... }
}
```

### AIエージェント向け: ブラウザコンソールAPI

各プラグインは共通ランタイム window.KINTAUROS を搭載しており、ブラウザの開発者コンソールから設定の読み取り・検証・保存ができます。設定の保存(save: true)はkintoneの制約上、プラグイン設定画面でのみ成功します。

```
KINTAUROS.config.plugins()                   // このページのKINTAUROSプラグインID一覧
KINTAUROS.config.describeAll()               // 同居プラグインすべての設定サマリ
KINTAUROS.config.of('<プラグインID>').schema()    // 設定のJSON Schema
KINTAUROS.config.of('<プラグインID>').export()    // 現在の設定(封筒つき)
KINTAUROS.config.of('<プラグインID>').validate(x) // 保存せず検証
KINTAUROS.config.of('<プラグインID>').diff(x)     // 現在の設定との差分
await KINTAUROS.config.of('<プラグインID>').import(x, { save: true }) // 検証して保存(設定画面のみ)
```

登録が1件だけのページでは of(...) を省略できます(例: KINTAUROS.config.export())。

## トラブルシューティング

**ビューを開いても地図が表示されない**

アプリ設定 > プラグイン からジオスタジオの設定画面を開き、対象のカスタマイズビュー・タイトルフィールド・ビューを設定して保存し、「アプリを更新」してください。表示されるのは設定で指定したビューだけです。

**E001: 設定されたフィールドが見つかりません**

設定後にフィールドが削除・変更された状態です。プラグイン設定画面を開き、各ビューのフィールドを現在のフォームに合わせて選び直して保存してください。

**一部のレコードが地図に表示されない**

ピンマップは緯度・経度が未入力・不正(数値として読めない、または範囲外)のレコードを表示しません(画面上部に「〜件は表示していません」と件数が出ます)。統計バブルはサイズ基準の値が0以下・未入力のレコードも対象外です。住所しかない場合は、設定画面の一括ジオコーディングで緯度・経度を作成してください。

**都道府県マップで「該当なし」になるレコードがある**

都道府県フィールドの値から都道府県名を判定できていません。値が都道府県名で始まっているか(「東京都千代田区…」は可、「千代田区…」は不可)、表記ゆれ(スペース・略称など)がないかを確認してください。

**一括ジオコーディングで「住所が見つからず」になる**

国土地理院の住所検索APIで該当が見つからなかった住所です。ビル名・部屋番号を除く、丁目・番地をハイフン表記にするなど表記を整えて再実行してください(変換済みのレコードはスキップされるため、失敗した分だけ再変換されます)。

**地図がホイールで拡大縮小できない**

誤操作防止のため、ホイール単独ではズームしない仕様です。Ctrlキー(Macは⌘キー)を押しながらホイール操作するか、地図左上のズームボタンをお使いください。

## エラーコードと診断情報

ジオスタジオを含むKINTAUROSプラグインは、エラー発生時にブラウザのコンソールへ統一形式のログを出力します。人間向けの1行に続けて、機械可読なJSON(code / plugin / version / appId / message / doc)を出力し、doc には該当エラーの解説ページのURLが入ります。

```
[KINTAUROS <プラグインID>@<バージョン>] E001: 設定されたフィールドが見つかりません: ...
{"kintauros":{"code":"E001","plugin":"...","version":"...","appId":"...","message":"...","doc":"https://kintauros.com/docs/errors/E001"}}
```

各エラーコードの意味と対処は[エラーコード一覧](https://kintauros.com/docs/errors/)を参照してください。また、プラグイン設定画面の「サポート用情報をコピー」から、環境・バージョン・ライセンス状態・直近のエラーを含む診断情報をコピーできます(レコードの内容や個人情報は含まれません)。お問い合わせの際はこの情報を添えてください。

## ライセンスについて

- 初回利用時は、プラグイン設定画面の「利用開始」ボタンから60日間の無料トライアルを開始できます(カード登録不要)。

- トライアル・契約の期限が切れるとプラグインの動作は停止し、画面に案内が表示されます。[料金プラン](https://kintauros.com/#pricing)から契約すると同じ設定のまま再開できます。

- ライセンス確認のための外部通信で送信されるのは、kintoneドメイン名・プラグインID・バージョンのみです。レコードの内容や個人情報が外部に送信されることはありません。

- ライセンスサーバーに一時的に接続できない場合も、プラグインは一定期間動作を継続する設計です。

## サポート

解決しない場合は[お問い合わせ](https://kintauros.com/contact/)からご連絡ください。その際、プラグイン設定画面の「サポート用情報をコピー」でコピーした診断情報を添えていただくと、調査がスムーズです。

最終更新: 2026-09-12 / 対象バージョン: v1.3.1