Lewati ke isi
ID
Dapatkan kunci API
Jelajahi dokumentasi

Panduan

Tambahkan pencarian ke aplikasi

Buat formulir pencarian, simpan kunci API pada backend Anda, dan gunakanlah fungsi pencarian yang sama dalam suatu alat agen.

Di halaman ini

What you will build

Bentuk pencarian lokal dengan link peringkat, snippet dan penggunaan kredit. Memerlukan Node.js 22+, sebuah kunci dengan google_search ijin dan kredit yang tersedia. Tidak. npm Paket dibutuhkan. Bagian agen opsional menggunakan fungsi backend yang sama.

Simpan dalam format flashdata-search-demoTujuan
search.mjsMemanggil FlashData dari backend; dibagikan oleh formulir dan alat agen.
server.mjsMelayani halaman lokal dan GET /search titik akhir.
index.htmlTampilkan sumber, hasil dan galat kosong.
Bash atau PowerShell
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo

Set kunci API Anda

Gunakan FLASHDATA_API_KEY jika sudah diset. Jika tidak, gunakan prompt tersembunyi di bawah di terminal yang akan menjalankan kode. Seorang agen dapat memuat variabel yang sama dari toko rahasia.

Menentukan kunci
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY

1. Buat fungsi pencarian

Simpan sebagai search.mjs dalam folder projek Anda. Satu panggilan kembali ke lima hasil web, mereka URLs dan penggunaan sebenarnya. Fungsi memvalidasi masukan, mempertahankan urutan hasil, menghapus duplikasi URLs dan menyimpan kunci dari data yang dikembalikan. The 500Batas karakter adalah pilihan aplikasi.

search.mjs
// search.mjs — server only; Node.js 22+
export async function searchWeb(query) {
  if (typeof query !== "string" || !query.trim() || query.length > 500) {
    throw Object.assign(new Error("Enter a query of 1–500 characters."), { status: 400 });
  }
  const apiKey = process.env.FLASHDATA_API_KEY;
  if (!apiKey) throw new Error("Set FLASHDATA_API_KEY on the server.");
  let response;
  try {
    response = await fetch("https://data.flashdata.dev/v1/queries/realtime", {
      method: "POST", redirect: "error", signal: AbortSignal.timeout(70000),
      headers: { "X-API-Key": apiKey, "Content-Type": "application/json" },
      body: JSON.stringify({ source: "google_search", query: query.trim(),
        params: { num: 5, gl: "us", hl: "en" } }),
    });
  } catch {
    throw new Error("Search outcome unknown. Check FlashData History before retrying.");
  }
  if (!response.ok) {
    throw Object.assign(new Error("Search failed: HTTP " + response.status), {
      status: response.status, retryAfter: response.headers.get("retry-after"),
    });
  }
  const data = await response.json();
  if (data.status !== "done" || !Array.isArray(data.results)) {
    throw new Error("Search did not finish. Check FlashData History.");
  }
  const seen = new Set();
  const sources = [];
  for (const [index, item] of (data.results[0]?.organic ?? []).entries()) {
    let url;
    try { url = new URL(item.link); } catch { continue; }
    if (!["https:", "http:"].includes(url.protocol) || seen.has(item.link)) continue;
    seen.add(item.link);
    sources.push({ rank: item.position ?? index + 1, title: item.title ?? item.link,
      url: item.link, snippet: item.snippet ?? "" });
  }
  return { query: query.trim(), sources, usage: data.usage,
    retrievedAt: new Date().toISOString() };
}

2. Tambahkan backend lokal

Simpan sebagai server.mjs di samping search.mjs. GET /search? q =... memanggil fungsi; GET / melayani formulir Anda akan membuat berikutnya. Server hanya mendengarkan 127.0.0.1.

server.mjs
// server.mjs — local demo; keep your existing app's authentication in production.
import { createServer } from "node:http";
import { readFile } from "node:fs/promises";
import { searchWeb } from "./search.mjs";

createServer(async (req, res) => {
  const url = new URL(req.url, "http://127.0.0.1:8787");
  res.setHeader("Cache-Control", "no-store");
  try {
    if (req.method === "GET" && url.pathname === "/") {
      const html = await readFile(new URL("./index.html", import.meta.url));
      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
      return res.end(html);
    }
    if (req.method !== "GET" || url.pathname !== "/search") {
      res.writeHead(404); return res.end("Not found");
    }
    const result = await searchWeb(url.searchParams.get("q"));
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify(result));
  } catch (error) {
    if (error.retryAfter) res.setHeader("Retry-After", error.retryAfter);
    res.writeHead(error.status ?? 502, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: error.message }));
  }
}).listen(8787, "127.0.0.1", () => console.log("Open http://127.0.0.1:8787"));

3. Tampilkan hasil pada aplikasi Anda

Simpan sebagai index.html dalam folder yang sama. Formulir ini menangani pemuatan, hasil kosong dan kesalahan. Ini memanggil backend Anda dan memasukkan snippet sebagai teks, jadi bukan kunci API ataupun eksternal HTML mencapai halaman.

index.html
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Web search</title>
<h1>Search the web</h1>
<form id="search">
  <label>Query <input name="q" required maxlength="500" value="battery recycling research"></label>
  <button>Search</button>
</form>
<p id="status" role="status"></p>
<ol id="results"></ol>
<script type="module">
const form = document.querySelector("#search");
const status = document.querySelector("#status");
const results = document.querySelector("#results");
form.addEventListener("submit", async (event) => {
  event.preventDefault();
  form.querySelector("button").disabled = true;
  results.replaceChildren(); status.textContent = "Searching…";
  try {
    const q = new FormData(form).get("q");
    const response = await fetch("/search?q=" + encodeURIComponent(q));
    const data = await response.json();
    if (!response.ok) {
      const retryAfter = response.headers.get("Retry-After");
      throw new Error(data.error + (retryAfter ? " · Retry-After: " + retryAfter : ""));
    }
    for (const source of data.sources) {
      const li = document.createElement("li");
      const link = document.createElement("a");
      link.href = source.url; link.textContent = source.title;
      const excerpt = document.createElement("p");
      excerpt.textContent = source.snippet;
      li.append(link, excerpt); results.append(li);
    }
    const credits = data.usage?.credits ?? "not reported";
    status.textContent = (data.sources.length
      ? data.sources.length + (data.sources.length === 1 ? " source" : " sources")
      : "No matching pages. Try a broader query.") + " · Credits used: " + credits;
  } catch (error) { status.textContent = error.message; }
  finally { form.querySelector("button").disabled = false; }
});
</script>
</html>

4. Jalankan pencarian pertama Anda

Jalankan dari flashdata-search-demo di terminal di mana Anda mengatur kunci. Buka URL dan klik Cari sekali. Setiap kirim membuat kuiri yang dibayar; membuka halaman atau mengedit masukan tidak membuat apapun. Menghentikan server lokal dengan Ctrl + C ketika selesai.

  1. Masukkan topik spesifik, seperti laju pemulihan daur ulang baterai.
  2. Berharap judul terkait, snippet dan kredit dikembalikan dalam usage.credits. Hasil bervariasi; nol sumber adalah pencarian selesai yang valid.
Dalam twitter-search- demo
node server.mjs
Buka dalam peramban Anda
http://127.0.0.1:8787

Hasil aplikasi Anda menerima

(Dalam bentuk) lafal ayat ini menjadi Haal atau kata keterangan keadaan bagi Dhamir yang terkandung di dalam lafal Iqra '. URLs dan penggunaan di bawah ini adalah ilustratif. Sebuah pencarian mengembalikan snippet dan link. Gunakan pembaca halaman ketika fitur Anda memerlukan teks halaman penuh.

GET /search?q=...
{
  "query": "battery recycling research",
  "sources": [
    {
      "rank": 1,
      "title": "Example source",
      "url": "https://example.org/research",
      "snippet": "A returned search excerpt."
    }
  ],
  "usage": {
    "credits": 0.02
  },
  "retrievedAt": "2026-11-04T00:00:00.000Z"
}

Pakai ulang pencarian dalam suatu alat agen

Opsional: simpan search-tool.mjs di samping search.mjs. Pelari hanya menerima search_web dan kueri. Buat satu pelari per tugas dan tetap di atas model penukaran tugas itu; batas percobaan maxCalls, termasuk usaha gagal. Ini tidak menetapkan batas pengeluaran kredit.

flashdata-search-demo/search-tool.mjs
// search-tool.mjs — one runner per task, reused across its model turns.
import { searchWeb } from "./search.mjs";

export const searchTool = {
  name: "search_web",
  description: "Find ranked web URLs and snippets for a focused query.",
  inputSchema: {
    type: "object", additionalProperties: false,
    properties: { query: { type: "string", minLength: 1, maxLength: 500 } },
    required: ["query"],
  },
};
export function createSearchToolRunner({ maxCalls = 2 } = {}) {
  if (!Number.isSafeInteger(maxCalls) || maxCalls < 1) {
    throw new Error("maxCalls must be a positive integer.");
  }
  let attempts = 0;
  return async function runTool(name, args) {
    if (name !== searchTool.name) throw new Error("Unknown tool: " + name);
    if (!args || typeof args !== "object" || Array.isArray(args) ||
        Object.keys(args).some(key => key !== "query") ||
        typeof args.query !== "string" || !args.query.trim() || args.query.length > 500) {
      throw new Error("Expected only query: a string of 1–500 characters.");
    }
    if (attempts >= maxCalls) throw new Error("Search call limit reached for this task.");
    attempts++; // Reserve before awaiting; a failed attempt still counts.
    return searchWeb(args.query);
  };
}

Coba alat secara langsung

Simpan tool-demo.mjs dalam flashdata-search-demo, kemudian jalankan perintah di bawah dari folder dengan kunci API yang sama. Pemeriksaan opsional ini membuat satu query FlashData tambahan tanpa memanggil sebuah model. Mengharapkan JSON dengan kueri, sumber, penggunaan dan retrievedAt - bentuk hasil yang sama dengan formulir.

flashdata-search-demo/tool-demo.mjs
// tool-demo.mjs — one direct tool call; no model-provider dependency.
import { createSearchToolRunner, searchTool } from "./search-tool.mjs";

if (process.argv.length !== 3) {
  console.error('Usage: node tool-demo.mjs "your search query"');
  process.exit(1);
}
const runTool = createSearchToolRunner({ maxCalls: 1 });
const result = await runTool(searchTool.name, { query: process.argv[2] });
console.log(JSON.stringify(result, null, 2));
Jalankan sekali dari flashdata-search- demo
node tool-demo.mjs "battery recycling research"

Hubungkan ke model Anda

Latihan demo fungsi alat. Kerangka kerja Anda menyediakan koneksi model dan loop pesan. Cari kembali link dan snippet; membaca halaman yang dipilih sebelum menggunakan isi lengkap mereka dalam sebuah jawaban. Untuk melanjutkan atau didistribusikan tugas, pertahankan jumlah dan hasil percobaan dengan tugas ID.

  1. Register searchTool.name, deskripsi dan inputSchema menggunakan format definisi kerangka kerja Anda. Simpan kunci API di lingkungan backend.
  2. Pada awal tugas, panggil createSearchToolRunner ({ maxCalls: 2 }). Untuk setiap panggilan alat model, parse argumen JSON nya dan lulus nama dan parsed objek ke pelari yang sama. Tolak JSON yang tidak sah sebelum pengiriman.
  3. Kembalikan hasil JSON ke model sebagai hasil alat dengan panggilan asli ID. Menjaga sources[].url untuk kutipan. Jika eksekusi gagal atau mencapai batas, kembalikan error; jangan buat pelari baru untuk mencobanya kembali.

Menangani kegagalan dan kapal itu

Untuk penyebaran, pindahkan /search di belakang tanda aplikasi Anda masuk dan per- batas pengguna. Simpan kunci API dalam konfigurasi server, pertahankan penggunaan dengan permintaan dan buat isi eksternal sebagai teks. Realtime cocok untuk bentuk interaktif ini; gunakan asinc untuk pekerjaan latar belakang.

SituasiPerilaku app
ERR_MODULE_NOT_FOUND / ENOENTSimpan semua berkas dalam flashdata-search- demo dan jalankan dari folder itu. Simpan index.html sebelum membuka halaman.
EADDRINUSEPort 8787 dikuasai. Hentikan proses demo sebelumnya sebelum memulai proses lain.
Batas panggilan pencarian tercapaiTugas itu digunakan untuk usaha yang diperbolehkan. Selesai dengan bukti dikumpulkan atau melaporkan limit; membuat pelari baru akan me-reset hitungannya.
Hasil kosongTampilkan keadaan kosong dan biarkan pengguna menyempurnakan permintaan; jangan coba secara otomatis.
401 / 403 / 402Periksa kunci server, izin google_search dan kredit rekening.
429Tunggu Retry-After ketika diberikan; permintaan batas per pengguna sebelum memanggil FlashData.
Galat waktu / jaringanTunjukkan hasil yang tidak pasti. Inspeksi History sebelum mengirim kuiri dibayar yang sama lagi.