Baidu SEO Keyword Ranking

能力概述

查询指定域名在百度PC搜索中的关键词排名情况，返回关键词列表及对应排名、预估流量、PC指数、收录量、目录、标题等SEO核心指标，支持分页查询和目录筛选。

• Endpoint: POST https://app-bo4w33bsdqm9-api-DLEO4zmpN5ja-gateway.appmiaoda.com/seo/baidu/pc/keyword
• Content-Type: application/x-www-form-urlencoded
• 认证模式: platform_managed（密钥由平台注入）
• 响应格式: JSON

响应示例：

{
  "code": 200,
  "msg": "成功",
  "taskNo": "41020892700032664119",
  "data": {
    "Pages": 1,
    "Uv": "1~1",
    "Total": 14,
    "Count": 14,
    "Domain": "www.jumdata.com",
    "Current": 1,
    "List": [
      {
        "RankStr": "1-2",
        "SiteCount": 0,
        "Keyword": "聚美智数",
        "Calalog": "/",
        "Title": "关于我们-聚美智数",
        "Index": 90,
        "Url": "https://www.jumdata.com/about"
      }
    ]
  }
}

参数说明

请求参数：

返回字段说明：

错误码：

生成期用法（Agent 直接调用）

const apiKey = process.env["INTEGRATIONS_API_KEY"]!; // platform_managed 密钥由平台注入

interface KeywordItem {
  RankStr: string;
  SiteCount: number;
  Keyword: string;
  Calalog: string;
  Title: string;
  Index: number;
  Url: string;
}

interface KeywordRankingData {
  Pages: number;
  Uv: string;
  Total: number;
  Count: number;
  Domain: string;
  Current: number;
  List: KeywordItem[];
}

/**
 * 查询指定域名在百度PC端的关键词排名数据。
 * @param domain - 查询的域名，例如 "www.example.com"
 * @param catalog - 可选，目录名称，默认选择全部数据
 * @param page - 可选，分页页码，默认第 1 页
 * @returns 关键词排名数据对象
 */
async function queryBaiduPcKeywordRanking(
  domain: string,
  catalog?: string,
  page?: string,
): Promise<KeywordRankingData> {
  const params: Record<string, string> = { domain };
  if (catalog) params.catalog = catalog;
  if (page) params.page = page;

  const response = await fetch(
    "https://app-bo4w33bsdqm9-api-DLEO4zmpN5ja-gateway.appmiaoda.com/seo/baidu/pc/keyword",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        "X-Gateway-Authorization": `Bearer ${apiKey}`,
      },
      body: new URLSearchParams(params).toString(),
    },
  );

  if (!response.ok) throw new Error(`HTTP error: ${response.status}`);

  const json = await response.json();
  if (json.code !== 200) throw new Error(`API error ${json.code}: ${json.msg}`);

  return json.data;
}

// 使用示例
const result = await queryBaiduPcKeywordRanking("www.jumdata.com", undefined, "1");
console.log(`共 ${result.Total} 条关键词，预估流量：${result.Uv}`);
for (const item of result.List) {
  console.log(`[${item.RankStr}] ${item.Keyword} - ${item.Title}`);
}

生成后用法（应用内通过 Edge Function 调用）

Edge Function

// edge-functions/baidu-seo-keyword-ranking.ts
import { serve } from "https://deno.land/std/http/server.ts";

serve(async (req: Request): Promise<Response> => {
  if (req.method !== "POST") {
    return new Response("Method Not Allowed", { status: 405 });
  }

  // --- 解析客户端请求 ---
  let domain: string;
  let catalog: string | undefined;
  let page: string | undefined;
  try {
    const body = await req.json();
    domain = body.domain;
    if (!domain) throw new Error("Missing domain");
    catalog = body.catalog;
    page = body.page;
  } catch {
    return new Response(JSON.stringify({ error: "Invalid request body" }), {
      status: 400,
      headers: { "Content-Type": "application/json" },
    });
  }

  // --- 注入平台密钥（不可暴露到前端） ---
  const apiKey = Deno.env.get("INTEGRATIONS_API_KEY");
  if (!apiKey) {
    return new Response(JSON.stringify({ error: "Server configuration error" }), {
      status: 500,
      headers: { "Content-Type": "application/json" },
    });
  }

  // --- 构建请求参数 ---
  const params: Record<string, string> = { domain };
  if (catalog) params.catalog = catalog;
  if (page) params.page = page;

  // --- 调用上游接口 ---
  const upstream = await fetch(
    "https://app-bo4w33bsdqm9-api-DLEO4zmpN5ja-gateway.appmiaoda.com/seo/baidu/pc/keyword",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        "X-Gateway-Authorization": `Bearer ${apiKey}`,
      },
      body: new URLSearchParams(params).toString(),
    },
  );

  // 转发配额/余额错误
  if (upstream.status === 429 || upstream.status === 402) {
    const errText = await upstream.text();
    return new Response(errText, {
      status: upstream.status,
      headers: { "Content-Type": "application/json" },
    });
  }

  if (!upstream.ok) {
    return new Response(
      JSON.stringify({ error: `Upstream error: ${upstream.status}` }),
      { status: 502, headers: { "Content-Type": "application/json" } },
    );
  }

  const data = await upstream.json();
  return new Response(JSON.stringify(data), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
});

前端调用

推荐方式（supabase client 可用时）：

/**
 * 通过 Edge Function 查询百度PC关键词排名。
 * @param domain - 查询的域名
 * @param catalog - 可选，目录名称
 * @param page - 可选，分页页码
 * @returns 关键词排名数据对象
 */
async function fetchBaiduPcKeywordRanking(
  domain: string,
  catalog?: string,
  page?: string,
) {
  const { data, error } = await supabase.functions.invoke(
    "baidu-seo-keyword-ranking",
    { body: { domain, catalog, page } },
  );
  if (error) throw error;
  if (data.code !== 200) throw new Error(`API 错误 ${data.code}：${data.msg}`);
  return data.data;
}

备用方式（无法使用 supabase client 时）：

/**
 * 通过原生 fetch 调用 Edge Function 查询百度PC关键词排名。
 * @param domain - 查询的域名
 * @param catalog - 可选，目录名称
 * @param page - 可选，分页页码
 * @returns 关键词排名数据对象
 */
async function fetchBaiduPcKeywordRanking(
  domain: string,
  catalog?: string,
  page?: string,
) {
  const res = await fetch(
    `${import.meta.env.VITE_SUPABASE_URL}/functions/v1/baidu-seo-keyword-ranking`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ domain, catalog, page }),
    },
  );

  if (res.status === 429) {
    const err = await res.json();
    throw new Error(`配额已用尽：${err.message ?? res.statusText}`);
  }
  if (res.status === 402) {
    const err = await res.json();
    throw new Error(`余额不足：${err.message ?? res.statusText}`);
  }
  if (!res.ok) throw new Error(`请求失败：${res.status}`);

  const json = await res.json();
  if (json.code !== 200) throw new Error(`API 错误 ${json.code}：${json.msg}`);

  return json.data;
}

注意事项

• 密钥安全：INTEGRATIONS_API_KEY 仅可在 Edge Function 服务端读取，严禁暴露到前端。
• 错误处理：务必处理 429（配额超限）和 402（余额不足）两类错误；业务层还需处理 400（域名为空或参数错误）。
• 计费：原价 ¥0.90/次，折扣价 ¥0.50/次，建议按需查询，避免不必要的重复调用。
• 分页：每页最多返回 100 条数据，若 data.Pages > 1，需通过递增 page 参数分页获取全量数据。
• 字段拼写：API 响应中目录字段为 Calalog（非 Catalog），使用时注意拼写。
• 排名格式：RankStr 为字符串排名区间（如 "1-2"），非整数，不可直接用于数值比较。