如何使用 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。