npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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_xxxxx

API キーが解決できない場合は 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] までご連絡ください。

関連ドキュメント

ライセンス

MIT — LICENSE 参照。