API の概要

Suede Search API は、プライベートで広告のない検索結果を JSON として返す ── Suede を支えているのと同じ、 ウェブ・画像・ニュース・動画・ショッピングの結果を、広告も追跡もなく、あなたにひも付くクエリ履歴も保持しない。

ベース URL

すべてのアカウントを、ひとつのグローバルなエンドポイントがまかなう:

https://api.suede.io

リクエストは自動的に最寄りのインフラ地域へ振り分けられる ── どの地域も同じ API を提供し、結果の重み付けは クエリごとに任意の gl パラメータで選べる。設定すべきものは何もない。

インタラクティブなエクスプローラー

API のホストは、ブラウザ内でライブに動く参照を提供する。ホストのルート(https://api.suede.io/)を開くと、 /scalar/v1 のエクスプローラーへリダイレクトされる。そこではあらゆるエンドポイントがドキュメント化され、 あなた自身のキーで呼び出せる。機械可読の OpenAPI 記述は、クライアントを生成したり API を別のツールに取り込んだり したい場合のために、/openapi/v1.json にある。

認証

すべてのリクエストは、API キーをベアラートークンとして携える必要がある:

Authorization: Bearer suede_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

キーは Suede アカウントで作成する ── 認証 を参照のこと。課金対象の検索エンドポイントには、 有効な Suede メンバーシップ と API クレジット残高が正であること が必要である。

最初のリクエスト

curl "https://api.suede.io/v1/search?q=hello+world" \
  -H "Authorization: Bearer $SUEDE_API_KEY"

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new("Bearer", Environment.GetEnvironmentVariable("SUEDE_API_KEY"));
var json = await http.GetStringAsync("https://api.suede.io/v1/search?q=hello+world");
Console.WriteLine(json);

const res = await fetch("https://api.suede.io/v1/search?q=hello+world", {
  headers: { Authorization: `Bearer ${process.env.SUEDE_API_KEY}` },
});
console.log(await res.json());

レスポンス

成功したレスポンスは HTTP 200 の JSON である。エラーは統一されたエンベロープを用いる:

{ "error": { "type": "invalid_request", "message": "Query parameter 'q' is required.", "request_id": "a1b2c3d4e5f6a7b8" } }

すべてのレスポンスには X-Request-Id ヘッダーが付く(エラーでは request_id として反映される)。サポートに連絡 する際にはこれを引用すること。エラー には型とステータスコードの全集合が列挙されており、 レート制限 はスロットリングを説明する。

バージョニング

現在のバージョンは v1 であり、/v1 パスプレフィックスの下でアクセスする。バージョンを上げることなくレスポンス に新しいフィールドが追加される場合があるため、防御的に解析し、未知のフィールドは無視すること。互換性を壊す変更は、 新しいバージョンプレフィックスの下で提供される。

エンドポイント一覧