ウェブ検索

最終更新 July 20, 2026

集約されたウェブ検索結果を JSON で返す。

TEXT

GET /v1/search

有効な API キー、有効なメンバーシップ、利用可能な API クレジットが必要である。

クエリパラメータ

名前	型	必須	既定	説明
`q`	string	はい	—	検索クエリ。Suede の検索演算子に対応する(例: `site:`、`filetype:`、`"exact phrase"`、`-exclude`)。
`safe`	string	いいえ	`on`	セーフサーチのレベル: `off`、`on`。認識されない値は `on` として扱われる。
`gl`	string	いいえ	(自動)	結果の重み付けに用いる二文字の地域/国コード(例: `us`、`gb`、`ca`、`de`、`jp`)。対応していないコードは無視される(プロバイダーの既定が適用される)。
`hl`	string	いいえ	(自動)	結果の二文字の言語コード(例: `en`、`es`、`fr`、`de`、`ja`)。対応していないコードは無視される。
`time`	string	いいえ	`any`	新しさのフィルター: `any`、`hour`、`day`、`week`、`month`、`year`。
`num`	integer	いいえ	(プロバイダーの既定)	希望する結果数。5〜100 にクランプされ、範囲外の値は 20 にフォールバックする。プロバイダーの既定を使うには省略する。

レスポンス

JSON

{
  "query": "hello world",
  "results": [
    {
      "title": "Example Domain",
      "url": "https://example.com/",
      "description": "This domain is for use in illustrative examples in documents."
    }
  ]
}

フィールド	型	説明
`query`	string	実行されたクエリ。
`results`	array	ウェブの結果。
`results[].title`	string	結果のタイトル。
`results[].url`	string	結果の URL。
`results[].description`	string	結果のスニペット / 説明。

例

cURL

curl -G "https://api.suede.io/v1/search" \
  -H "Authorization: Bearer $SUEDE_API_KEY" \
  --data-urlencode "q=site:example.com filetype:pdf annual report" \
  --data-urlencode "gl=us" \
  --data-urlencode "num=20"

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

JavaScript

const params = new URLSearchParams({ q: "hello world", gl: "us", num: "20" });
const res = await fetch(`https://api.suede.io/v1/search?${params}`, {
  headers: { Authorization: `Bearer ${process.env.SUEDE_API_KEY}` },
});
const data = await res.json();
for (const r of data.results) console.log(r.title, r.url);

課金

各呼び出しは、前払いの API クレジットから差し引かれる。深い結果数(num が 10 を超える場合)は、複数の上流ページ取得に広がることがあり、それに応じて課金される。残高はいつでも使用状況で確認できる。