如何使用 JavaScript 調用 Talordata SERP API

JavaScript 很適合用來做 SERP API 工作流。

你可以把它用在 backend service、內部 SEO 工具、Next.js 應用、AI Agent、資料收集腳本，或每天定時檢查搜尋結果的排程任務裡。

目標很簡單：

send query
→ get structured search results
→ parse useful fields
→ store or pass the data into your product

Talordata SERP API 可以幫助開發者收集結構化搜尋結果資料，並用在 SEO dashboard、排名追蹤系統、競品監控工具、AI Agent 和市場研究 workflow 裡。

這篇文章會示範如何用 JavaScript 調用 Talordata SERP API、解析搜尋結果、處理錯誤、批量查詢關鍵字、匯出 CSV，並為 AI workflow 準備精簡搜尋上下文。

快速回答

要用 JavaScript 使用 Talordata SERP API，可以建立一個 Node.js 腳本，從環境變數讀取 API key，向 SERP API endpoint 發送 POST request，傳入 engine、q、location、gl、hl、device、num 等參數，然後解析返回的 JSON。

基本流程如下：

JavaScript app
→ SERP API request
→ JSON response
→ parse organic results
→ store results or send them to an AI / SEO workflow

什麼時候需要在 JavaScript 中使用 SERP API？

當你的應用需要把搜尋引擎結果當成資料使用時，SERP API 就很有用。

大多數情況下，JavaScript 做的事情並不複雜。它發送請求、接收結構化資料、清洗欄位，再把結果傳給下一個流程。

小水管，也能跑出很實用的資料流。🪄

Step 1：建立 Node.js 專案

建立一個新資料夾：

mkdir talordata-serp-js
cd talordata-serp-js
npm init -y

建議使用 Node.js 18 或以上版本，這樣可以直接使用內建 fetch API。

檢查 Node 版本：

node -v

如果你使用舊版 Node，可以安裝 node-fetch，或直接升級 Node。

Step 2：設定環境變數

不要把 API key 寫死在腳本裡。

macOS 或 Linux：

export TALORDATA_API_KEY="your_api_key_here"
export TALORDATA_SERP_ENDPOINT="your_serp_api_endpoint_here"

Windows PowerShell：

$env:TALORDATA_API_KEY="your_api_key_here"
$env:TALORDATA_SERP_ENDPOINT="your_serp_api_endpoint_here"

Endpoint 建議保持可配置。請使用你的 Talordata dashboard 或 API 文件中顯示的 endpoint。

API key 外洩不是小 bug，是一條拿著信用卡的小龍。

Step 3：發送第一個搜尋請求

建立 search.js 檔案。

const API_KEY = process.env.TALORDATA_API_KEY;
const SERP_ENDPOINT = process.env.TALORDATA_SERP_ENDPOINT;

if (!API_KEY) {
  throw new Error("Missing TALORDATA_API_KEY environment variable.");
}

if (!SERP_ENDPOINT) {
  throw new Error("Missing TALORDATA_SERP_ENDPOINT environment variable.");
}

async function searchGoogle(query) {
  const response = await fetch(SERP_ENDPOINT, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      engine: "google",
      q: query,
      location: "United States",
      gl: "us",
      hl: "en",
      device: "desktop",
      num: 10,
    }),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`SERP API request failed: ${response.status} ${errorText}`);
  }

  return response.json();
}

async function main() {
  const data = await searchGoogle("best project management software");
  console.log(JSON.stringify(data, null, 2));
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

執行：

node search.js

如果配置正確，你應該會收到搜尋結果 JSON。

Step 4：理解常用 request parameters

大多數 JavaScript 工作流一開始只需要少數參數。

對 SEO 和 AI 工作流來說，q、location、gl、hl 和 device 特別重要。搜尋結果會因國家、城市、語言和裝置而變化，沒有上下文的 query 容易誤導。查看完整的API文档>>

Step 5：解析自然搜尋結果

原始 JSON 有用，但大多數應用需要更小的資料結構。

建立 helper function：

function cleanText(value) {
  if (!value) return "";
  return String(value).replace(/\s+/g, " ").trim();
}

function getOrganicResults(data) {
  return data.organic_results || data.organic || data.results || [];
}

function normalizeOrganicResults(data) {
  const organicResults = getOrganicResults(data);

  return organicResults.map((item, index) => ({
    position: item.position || item.rank || index + 1,
    title: cleanText(item.title),
    url: item.link || item.url || "",
    snippet: cleanText(item.snippet || item.description),
    displayedLink: cleanText(item.displayed_link || item.displayedUrl),
  }));
}

在腳本中使用：

async function main() {
  const data = await searchGoogle("best project management software");
  const results = normalizeOrganicResults(data);

  console.table(results);
}

這樣輸出會更容易閱讀，也更容易入庫。

Step 6：檢查目標網域是否排名

SEO rank tracking 常常需要知道某個 domain 是否出現在結果中。

function extractHostname(url) {
  try {
    return new URL(url).hostname.replace(/^www\./, "");
  } catch {
    return "";
  }
}

function findTargetDomain(results, targetDomain) {
  const target = targetDomain.replace(/^www\./, "").toLowerCase();

  for (const result of results) {
    const hostname = extractHostname(result.url).toLowerCase();

    if (hostname === target || hostname.endsWith(`.${target}`)) {
      return {
        found: true,
        position: result.position,
        matchedUrl: result.url,
        title: result.title,
        snippet: result.snippet,
      };
    }
  }

  return {
    found: false,
    position: null,
    matchedUrl: "",
    title: "",
    snippet: "",
  };
}

範例：

async function main() {
  const keyword = "best project management software";
  const targetDomain = "example.com";

  const data = await searchGoogle(keyword);
  const results = normalizeOrganicResults(data);
  const ranking = findTargetDomain(results, targetDomain);

  console.log({
    keyword,
    targetDomain,
    ...ranking,
  });
}

這就是一個簡單的 rank tracking building block。

Step 7：批量查詢關鍵字

真實工作流通常不只查一個 query。

const KEYWORDS = [
  "best project management software",
  "crm software for small business",
  "email marketing tools",
];

const SEARCH_CONTEXT = {
  location: "United States",
  gl: "us",
  hl: "en",
  device: "desktop",
  num: 10,
};

async function searchWithContext(query, context) {
  const response = await fetch(SERP_ENDPOINT, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      engine: "google",
      q: query,
      ...context,
    }),
  });

  if (!response.ok) {
    const errorText = await response.text();
    throw new Error(`Request failed for "${query}": ${response.status} ${errorText}`);
  }

  return response.json();
}

async function runBatchSearch() {
  const rows = [];

  for (const keyword of KEYWORDS) {
    const data = await searchWithContext(keyword, SEARCH_CONTEXT);
    const results = normalizeOrganicResults(data);

    for (const result of results) {
      rows.push({
        keyword,
        location: SEARCH_CONTEXT.location,
        gl: SEARCH_CONTEXT.gl,
        hl: SEARCH_CONTEXT.hl,
        device: SEARCH_CONTEXT.device,
        ...result,
        collectedAt: new Date().toISOString(),
      });
    }
  }

  console.table(rows);
}

runBatchSearch().catch((error) => {
  console.error(error);
  process.exit(1);
});

這已經足夠支撐小型內部 SEO 腳本或 AI 搜尋原型。

如果規模變大，再加上 rate limiting、retry、queue 和 persistent storage。

Step 8：匯出 CSV

JavaScript 不需要額外套件也能生成 CSV。

import fs from "node:fs";

function escapeCsvValue(value) {
  const text = value == null ? "" : String(value);
  return `"${text.replace(/"/g, '""')}"`;
}

function writeCsv(rows, filename) {
  if (!rows.length) {
    fs.writeFileSync(filename, "", "utf8");
    return;
  }

  const headers = Object.keys(rows[0]);

  const lines = [
    headers.join(","),
    ...rows.map((row) =>
      headers.map((header) => escapeCsvValue(row[header])).join(",")
    ),
  ];

  fs.writeFileSync(filename, lines.join("\n"), "utf8");
}

如果你的專案使用 ES modules，在 package.json 中加入：

{
  "type": "module"
}

然後匯出 batch results：

async function runBatchSearchToCsv() {
  const rows = [];

  for (const keyword of KEYWORDS) {
    const data = await searchWithContext(keyword, SEARCH_CONTEXT);
    const results = normalizeOrganicResults(data);

    for (const result of results) {
      rows.push({
        keyword,
        location: SEARCH_CONTEXT.location,
        gl: SEARCH_CONTEXT.gl,
        hl: SEARCH_CONTEXT.hl,
        device: SEARCH_CONTEXT.device,
        position: result.position,
        title: result.title,
        url: result.url,
        snippet: result.snippet,
        displayedLink: result.displayedLink,
        collectedAt: new Date().toISOString(),
      });
    }
  }

  writeCsv(rows, "serp_results.csv");
  console.log(`Exported ${rows.length} rows to serp_results.csv`);
}

runBatchSearchToCsv().catch((error) => {
  console.error(error);
  process.exit(1);
});

這樣 JavaScript 腳本就能收集搜尋結果，並產生適合試算表使用的檔案。

Step 9：處理錯誤和重試

Network call 會失敗。API 可能返回錯誤。某些 query 可能沒有結果。

不要讓一個失敗關鍵字中斷整個 batch。

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function withRetry(fn, retries = 3, delayMs = 1000) {
  let lastError;

  for (let attempt = 1; attempt <= retries; attempt += 1) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      console.warn(`Attempt ${attempt} failed: ${error.message}`);

      if (attempt < retries) {
        await sleep(delayMs * attempt);
      }
    }
  }

  throw lastError;
}

使用方式：

const data = await withRetry(() => searchWithContext(keyword, SEARCH_CONTEXT));

Production system 中也建議記錄：

• request payload

• response status

• keyword

• location

• device

• timestamp

• retry count

這能讓排錯不像在雷雨天讀茶葉。

Step 10：把結果用於 AI workflow

如果你在做 AI assistant，不要把完整 SERP response 全部塞進模型。

只傳精簡上下文。

function buildSearchContext(results, limit = 5) {
  return results.slice(0, limit).map((result) => ({
    title: result.title,
    url: result.url,
    snippet: result.snippet,
    position: result.position,
  }));
}

範例：

async function getSearchContextForAi(query) {
  const data = await searchGoogle(query);
  const results = normalizeOrganicResults(data);

  return {
    query,
    results: buildSearchContext(results, 5),
  };
}

這適合：

• AI research assistant

• content brief generator

• RAG source discovery

• competitor summaries

• real-time market monitoring

• fact-checking workflow

結構化搜尋資料能讓模型更聚焦。原始頁面則很容易把 context window 變成一間混亂閣樓。

Best practices

把 API keys 放在環境變數中，不要提交到 Git。

先用一個 query 測通，再跑 batch jobs。先 debug request，再擴展。

始終保存 query context。保留 q、engine、location、gl、hl、device 和 collectedAt。

入庫前先 normalize response。資料庫不應依賴所有 raw API fields 永遠不變。

當工作流需要不同 result types 時，把 organic、ads、maps、shopping、news、videos 分開處理。

要有 retry，但不要無限 retry。沒有上限的 retry loop 只是小型機器人驚慌發作。

AI workflow 只傳模型需要的欄位：title、URL、snippet、position 和 source。

SEO workflow 要保存歷史快照。單次 SERP result 是照片，排名資料庫才是縮時攝影。

FAQ

可以用 JavaScript 調用 Talordata SERP API 嗎？

可以。你可以用 Node.js fetch、axios 或任何 HTTP client 調用 Talordata SERP API。大多數流程都是發送帶有搜尋參數的 POST request，然後取得結構化 JSON。

一定需要 Node.js 嗎？

如果是 backend script、scheduled job 或 server-side app，Node.js 是最常見選擇。不建議直接在前端 browser code 中調用 SERP API，因為那會暴露 API key。

一開始應該使用哪些搜尋參數？

可以從 engine、q、location、gl、hl、device 和 num 開始。這些參數覆蓋搜尋引擎、查詢、市場、語言、裝置和返回數量。

可以用於 SEO rank tracking 嗎？

可以。解析 organic results，匹配 target domain，保存 ranking position，然後針對同一組 keyword 和 location 持續重複執行。

可以用於 AI Agent 嗎？

可以。用 SERP API 收集最新搜尋結果，再把 title、URL、snippet 和 position 等精簡欄位傳給模型作為上下文。

應該保存 raw responses 嗎？

開發階段建議保存。Raw responses 有助於排查 parser 問題。Production 中通常保存 normalized fields，只有在合規、debug 或審計需要時才保留 raw responses。

應該使用 JSON 還是 HTML output？

大多數 JavaScript workflow 應該使用 JSON，尤其是 SEO dashboard、database 和 AI Agent。只有在需要原始 SERP 檢查或自訂解析時才使用 HTML。