@sateais/sdk
v0.2.0
Published
SateAIs REST API JavaScript/TypeScript SDK — SAR衛星画像の検出ジョブ投入・結果取得
Readme
@sateais/sdk
日本語 | English
SateAIs の公式 JavaScript / TypeScript SDK です。SAR 衛星画像の解析 API (船舶検出 / オイルスリック検出 / 新規・消失建物検出 / 時系列変化検出)に async/await でプログラムからアクセスできます。 現在の対応衛星は Sentinel-1 で、今後順次拡張を予定しています。
npm install @sateais/sdk依存ゼロ(標準 fetch を利用)・ESM / CommonJS デュアル出力・型定義(.d.ts)同梱。
Node.js 18+ およびモダンブラウザで動作します。
クイックスタート
import { Client } from "@sateais/sdk";
const client = new Client({ apiKey: process.env.SATEAIS_API_KEY });
const job = await client.analyze.ship({ scene_id: "S1A_IW_GRDH_..." });
const result = await client.jobs.wait(job.job_id); // 完了までポーリング
console.log(result.features.length, "ships found");認証
API キーは SateAIs コンソール で発行できます。
優先度: apiKey 引数 > 環境変数 SATEAIS_API_KEY
// 1) 明示指定
const client = new Client({ apiKey: "sk_live_xxxxx" });
// 2) 環境変数 SATEAIS_API_KEY から自動解決
const client = new Client();export SATEAIS_API_KEY=sk_live_xxxxxAPI キーが解決できない場合は AuthenticationError が送出されます。
クライアントオプション
new Client(options) で受け取れる主なオプション:
| オプション | 既定 | 説明 |
| --- | --- | --- |
| apiKey | 環境変数 SATEAIS_API_KEY | API キー |
| baseUrl | https://api.spcsft.com/api/v1 | API ベース URL(末尾スラッシュは自動除去) |
| timeoutMs | 30_000 | 1 リクエストあたりのタイムアウト(ms)。0 / 負値で無効化 |
| fetch | グローバル fetch | 差し替え用の fetch 実装 |
ClientのtimeoutMsは 1 リクエスト単位のタイムアウトです。jobs.waitのtimeoutMs(完了までの全体待ち時間)とは別物なので混同しないでください。0または負値を指定するとタイムアウトを無効化します(即時 abort にはなりません)。
SDK
検出メソッド
| メソッド | 入力パターン |
| --- | --- |
| client.analyze.ship(...) | scene_id、または polygon+date |
| client.analyze.oilslick(...) | 同上 |
| client.analyze.newbuilding(...) | polygon+date_start+date_end |
| client.analyze.disappearbuilding(...) | 同上 |
| client.analyze.timeseries(...) | 同上 |
入力パターンは 2 系統あります。
// scene_id 系(ship / oilslick): シーンID指定、または polygon + 単一日付
await client.analyze.ship({ satellite_id: "sentinel-1", scene_id: "S1A_IW_GRDH_..." });
await client.analyze.oilslick({
satellite_id: "sentinel-1",
polygon: "POLYGON((...))", // WKT
date: "2026-05-01",
date_direction: "before", // 任意
orbit_direction: "ascending", // 任意
});
// polygon + 期間 系(newbuilding / disappearbuilding / timeseries)
await client.analyze.timeseries({
satellite_id: "sentinel-1",
polygon: "POLYGON((...))", // WKT
date_start: "2026-01-01",
date_end: "2026-05-01",
orbit_direction: "ascending", // 任意
});satellite_id の現状の対応値は "sentinel-1" です。戻り値は JobCreateResponse
(job_id / status / created_at 等)。詳細パラメータは
API リファレンス を参照してください。
入力上限
polygon の面積と期間には API 側の上限があります(超過時はジョブ投入が ValidationError で拒否されます)。
| メソッド | 面積上限 | 期間上限 |
| --- | --- | --- |
| newbuilding / disappearbuilding | 30000 km² | — |
| timeseries | 50 km² | date_start〜date_end は 3 年以内 |
ship/oilslickは単一シーン処理のため面積上限はありません。polygon+date指定時はdateを基準に ±14 日以内で最も近いシーンを自動選択します。
投入前プレビュー
検出メソッドと同名・同パラメータの client.preview.<name>() で、ジョブを投入せずに
消費クレジットの見積もり・残高・AOI カバレッジを確認できます。プレビューでクレジットは
消費されません。
const preview = await client.preview.newbuilding({
polygon: "POLYGON((...))",
date_start: "2026-01-01",
date_end: "2026-05-01",
});
console.log(preview.credits.estimated); // 消費クレジットの見積もり(上限値)
console.log(preview.credits.balance); // 現在の残高
console.log(preview.credits.sufficient); // 残高が見積もりに対して十分か
console.log(preview.coverage?.ratio); // AOI のシーン被覆率(0.0〜1.0)
console.log(preview.warnings); // LOW_AOI_COVERAGE などの警告
- 残高不足はエラーになりません(
credits.sufficient: falseとして返ります)。 実際にジョブを投入した場合は 402(InsufficientCreditsError)になります。scene_id指定など面積が確定しない入力ではクレジットを見積もれず、credits.estimatedはnull(warningsにCREDITS_NOT_ESTIMABLE)になります。- 実際の消費クレジットが見積もりを上回ることはありません(見積もりは上限値)。
- シーン検索が失敗・該当なしの場合、
coverageはnullになります。- プレビューが通ってもジョブ投入時に失敗する場合があります(同時実行上限 429 など)。
ジョブ管理
const job = await client.jobs.status(jobId); // 現在の状態を1回取得
const geojson = await client.jobs.result(jobId); // 完了済ジョブの結果(GeoJSON)
const geojson = await client.jobs.wait(jobId, {
intervalMs: 60_000, // ポーリング間隔(既定 約60s)
timeoutMs: 3_600_000, // タイムアウト、未指定で無制限
onPoll: (job) => console.log(job.status), // 各ポーリング時のコールバック
});検出には 30〜60 分かかる場合があります。
jobs.waitの既定ポーリング間隔は これに合わせて約 60 秒です。
jobs.waitはcompletedで結果を返し、failedおよびcancelled/expiredなどの終端ステータス(未知のステータスを含む)ではJobFailedErrorを送出して ポーリングを止めます。timeoutMsは未指定で無制限です。
例外
すべての例外は基底クラス SateaisError を継承します。
| 例外 | 発生条件 |
| --- | --- |
| AuthenticationError | 401 / 403、または API キー未解決 |
| ValidationError | 400(必須パラメータ不正など) |
| InsufficientCreditsError | 402(クレジット不足) |
| NotFoundError | 404 / 410(結果の保持期限切れ含む) |
| RateLimitError | 429(レート制限) |
| SateaisApiError | 上記以外の HTTP エラー(status / code / message を保持) |
| ResponseParseError | 2xx 応答のボディが JSON でない(status を保持。transport / パース層の問題) |
| JobFailedError | wait() 中にジョブが failed / 終端外ステータス(errorCode / errorMessage を保持) |
| JobTimeoutError | wait() がタイムアウト |
import { Client, JobFailedError, RateLimitError } from "@sateais/sdk";
try {
const result = await client.jobs.wait(job.job_id);
} catch (err) {
if (err instanceof JobFailedError) {
console.error("検出失敗:", err.errorCode, err.errorMessage);
} else if (err instanceof RateLimitError) {
console.error("レート制限に達しました");
} else {
throw err;
}
}ESM / CJS / TypeScript
- ESM:
import { Client } from "@sateais/sdk"; - CommonJS:
const { Client } = require("@sateais/sdk"); - 型定義同梱:
.d.tsをパッケージに含むため、追加の@types/*なしで型補完が効きます。
サポート
技術的なお問い合わせは [email protected] までご連絡ください。
関連ドキュメント
- docs/ARCHITECTURE.md — 内部構造・設計方針
- docs/CONTRIBUTING.md — 開発者向けガイド
- CHANGELOG.md — 変更履歴
ライセンス
MIT — LICENSE 参照。
