API接口文档

API 接口文档

优资快报系统对外提供的API接口，支持通过API Key进行身份验证

🔑API Key 获取

在使用API接口之前，您需要先获取API Key。请前往管理后台生成您的API Key。

前往获取API Key→

身份验证

所有API请求都需要在请求头中包含API Key进行身份验证。

请求头格式：

X-API-Key: your_api_key_here

关键词查询接口

根据关键词名称查询SEO关键词的详细信息，包括搜索量、难度、CPC、竞争度等数据。支持精确查询和模糊查询两种模式。

接口地址

POST /api/admin/seo-ranking/keyword-search

请求头

Content-Type: application/json
X-API-Key: your_api_key_here

请求参数

{
  "keyword": "关键词名称",
  "searchMode": "exact",
  "limit": 50
}

keywordstring (必填) - 要查询的关键词名称

searchModestring (可选) - 查询模式，可选值："exact"（精确查询，默认）或 "fuzzy"（模糊查询）

limitnumber (可选) - 返回记录数量限制，仅对模糊查询有效。默认50条，最大100条

查询模式说明：

exact：精确匹配，返回完全匹配关键词名称的单条记录（默认模式）
fuzzy：模糊匹配，返回包含关键词的多条记录，按搜索量降序排列，默认返回50条，最多100条

响应示例

精确查询响应（单条记录）：

{
  "success": true,
  "data": {
    "id": 1,
    "keyword": "example keyword",
    "searchVolume": 1000,
    "keywordDifficulty": 45,
    "cpc": 1.5,
    "competition": 0.75,
    "numberOfResults": "1000000",
    "trendScore": 85,
    "commercialScore": 90,
    "overallScore": 88,
    "kws": 12,
    "language": "en",
    "serpFeatures": ["feature1", "feature2"],
    "keywordIntents": ["informational", "commercial"]
  }
}

模糊查询响应（多条记录，按搜索量降序）：

{
  "success": true,
  "data": [
    {
      "id": 1,
      "keyword": "white screen error",
      "searchVolume": 5000,
      "keywordDifficulty": 45,
      "cpc": 1.5,
      "competition": 0.75,
      "numberOfResults": "1000000",
      "trendScore": 85,
      "commercialScore": 90,
      "overallScore": 88,
      "kws": 12,
      "language": "en"
    },
    {
      "id": 2,
      "keyword": "white screen of death",
      "searchVolume": 3000,
      "keywordDifficulty": 50,
      "cpc": 2.0,
      "competition": 0.80,
      "numberOfResults": "800000",
      "trendScore": 80,
      "commercialScore": 85,
      "overallScore": 82,
      "kws": 10,
      "language": "en"
    }
  ],
  "count": 2
}

响应字段说明

字段	类型	说明
keyword	string	关键词名称
searchVolume	number	搜索量
keywordDifficulty	number	关键词难度
cpc	number	每次点击成本
competition	number	竞争度
trendScore	number	趋势分数
commercialScore	number	商业价值分数
overallScore	number	综合分数
language	string	语言代码

错误响应

401 - 认证失败

{
  "error": "认证失败"
}

400 - 参数错误

{
  "success": false,
  "error": "缺少关键词参数"
}

404 - 未找到

{
  "success": false,
  "error": "未找到该关键词"
}

代码示例

cURL - 精确查询（默认）

curl -X POST https://youzikuaibao.com.cn/api/admin/seo-ranking/keyword-search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"keyword": "example keyword", "searchMode": "exact"}'

cURL - 模糊查询（默认50条）

curl -X POST https://youzikuaibao.com.cn/api/admin/seo-ranking/keyword-search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"keyword": "white screen", "searchMode": "fuzzy"}'

cURL - 模糊查询（指定数量）

curl -X POST https://youzikuaibao.com.cn/api/admin/seo-ranking/keyword-search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"keyword": "white screen", "searchMode": "fuzzy", "limit": 20}'

Python - 精确查询

import requests

url = "https://youzikuaibao.com.cn/api/admin/seo-ranking/keyword-search"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key_here"
}
data = {
    "keyword": "example keyword",
    "searchMode": "exact"  # 精确查询（默认）
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
print(result)

Python - 模糊查询（默认50条）

import requests

url = "https://youzikuaibao.com.cn/api/admin/seo-ranking/keyword-search"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key_here"
}
data = {
    "keyword": "white screen",
    "searchMode": "fuzzy"  # 模糊查询，默认返回50条
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
print(f"找到 {result.get('count', 0)} 条记录")
for item in result.get('data', []):
    print(f"{item['keyword']}: {item['searchVolume']}")

Python - 模糊查询（指定数量）

import requests

url = "https://youzikuaibao.com.cn/api/admin/seo-ranking/keyword-search"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key_here"
}
data = {
    "keyword": "white screen",
    "searchMode": "fuzzy",
    "limit": 20  # 指定返回20条
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
print(result)

JavaScript (fetch) - 精确查询

fetch('https://youzikuaibao.com.cn/api/admin/seo-ranking/keyword-search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    keyword: 'example keyword',
    searchMode: 'exact'  // 精确查询（默认）
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

JavaScript (fetch) - 模糊查询（默认50条）

fetch('https://youzikuaibao.com.cn/api/admin/seo-ranking/keyword-search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    keyword: 'white screen',
    searchMode: 'fuzzy'  // 模糊查询，默认返回50条
  })
})
.then(response => response.json())
.then(data => {
  console.log(`找到 ${data.count} 条记录`);
  data.data.forEach(item => {
    console.log(`${item.keyword}: ${item.searchVolume}`);
  });
})
.catch(error => console.error('Error:', error));

JavaScript (fetch) - 模糊查询（指定数量）

fetch('https://youzikuaibao.com.cn/api/admin/seo-ranking/keyword-search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    keyword: 'white screen',
    searchMode: 'fuzzy',
    limit: 20  // 指定返回20条
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Google趋势词查询接口

根据关键词名称查询Google趋势词的详细信息，包括趋势数据、时间段、关联的SEO关键词数据等。

接口地址

POST /api/admin/google-trends-keyword/search

请求头

Content-Type: application/json
X-API-Key: your_api_key_here

请求参数

{
  "keyword": "关键词名称",
  "period": "时间段（可选）"
}

keywordstring (必填) - 要查询的Google趋势词名称

periodstring (可选) - 时间段，如 "past_1_hour", "past_4_hours", "past_1_day" 等

响应示例

{
  "success": true,
  "data": {
    "id": 1,
    "keyword": "example keyword",
    "period": "past_1_day",
    "keywordCount": 5,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T12:00:00.000Z",
    "trendData": [
      {
        "id": 1,
        "query": "example keyword",
        "trendsValue": 100,
        "period": 1,
        "hasData": true,
        "trendLink": "https://trends.google.com/...",
        "listType": "rising_searches",
        "collectedAt": "2025-01-01T12:00:00.000Z",
        "trendDate": "2025-01-01T00:00:00.000Z",
        "keywordId": 123
      }
    ],
    "seoData": {
      "id": 123,
      "keyword": "example keyword",
      "searchVolume": 1000,
      "keywordDifficulty": 45,
      "cpc": 1.5,
      "competition": 0.75,
      "trendScore": 85,
      "commercialScore": 90,
      "overallScore": 88,
      "kws": 12,
      "language": "en"
    }
  }
}

响应字段说明

字段	类型	说明
keyword	string	Google趋势词名称
period	string \| null	时间段
keywordCount	number	关键词数量
trendData	array	趋势数据列表（最近10条）
trendData[].trendsValue	number	趋势数值
trendData[].listType	string	列表类型（如 rising_searches, trending_searches）
seoData	object \| null	关联的SEO关键词数据（如果存在）
seoData.searchVolume	number \| null	搜索量
seoData.overallScore	number \| null	综合评分

错误响应

401 - 认证失败

{
  "error": "认证失败"
}

400 - 参数错误

{
  "success": false,
  "error": "缺少关键词参数"
}

404 - 未找到

{
  "success": false,
  "error": "未找到该Google趋势词"
}

代码示例

cURL

curl -X POST https://youzikuaibao.com.cn/api/admin/google-trends-keyword/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"keyword": "example keyword", "period": "past_1_day"}'

Python

import requests

url = "https://youzikuaibao.com.cn/api/admin/google-trends-keyword/search"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "your_api_key_here"
}
data = {
    "keyword": "example keyword",
    "period": "past_1_day"
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
print(result)

JavaScript (fetch)

fetch('https://youzikuaibao.com.cn/api/admin/google-trends-keyword/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    keyword: 'example keyword',
    period: 'past_1_day'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

竞品网站保存接口

用于保存竞品网站信息到系统。支持从 Traffic.cv 等数据源提取的网站数据。如果域名已存在，将自动更新现有记录；如果不存在，将创建新记录。

接口地址

POST /api/admin/competitor-websites

请求头

Content-Type: application/json
X-API-Key: your_api_key_here
或
Authorization: Bearer your_api_key_here

请求参数

{
  "name": "网站名称",
  "domain": "example.com",
  "description": "网站描述",
  "monthlyVisits": "1000000",
  "createdDate": "2020-01-01",
  "pageCount": 1000,
  "pagesPerVisit": 2.5,
  "backlinks": 50000,
  "publicRevenue": "100000",
  "cpmRate": "5.5",
  "globalRank": 1000,
  "avgDuration": "00:03:30",
  "bounceRate": "45.5",
  "searchTrafficRatio": "60.5",
  "notes": "备注信息",
  "tags": "标签1,标签2"
}

字段	类型	必填	说明
domain	string	是	网站域名（支持 example.com 或 https://example.com 格式）
name	string	否	网站名称
description	string	否	网站描述
monthlyVisits	string/number	否	月访问量
createdDate	string	否	域名创建日期（格式：YYYY-MM-DD）
pageCount	number	否	页面数量
pagesPerVisit	number	否	每次访问页面数
backlinks	number	否	外链数量
publicRevenue	string/number	否	公开收入
cpmRate	string/number	否	CPM 费率
globalRank	number	否	全球排名
avgDuration	string	否	平均停留时间（格式：HH:MM:SS 或秒数）
bounceRate	string/number	否	跳出率（百分比）
searchTrafficRatio	string/number	否	搜索流量比例（百分比）
notes	string	否	备注信息
tags	string	否	标签（多个标签用逗号分隔）

响应示例

成功响应（创建新记录）

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Example Website",
    "domain": "example.com",
    "description": "网站描述",
    "monthly_visits": "1000000",
    "created_date": "2020-01-01T00:00:00.000Z",
    "page_count": 1000,
    "pages_per_visit": 2.5,
    "backlinks": 50000,
    "global_rank": 1000,
    "avg_duration": 210,
    "bounce_rate": 45.5,
    "search_traffic_ratio": 60.5,
    "notes": "备注信息",
    "tags": "标签1,标签2",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  },
  "message": "竞品网站创建成功"
}

成功响应（更新现有记录）

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Updated Website Name",
    "domain": "example.com",
    ...
  },
  "message": "网站数据已更新"
}

错误响应

400 - 参数错误

{
  "success": false,
  "error": "域名为必填项"
}

403 - 无权限

{
  "success": false,
  "error": "无权限访问"
}

代码示例

cURL

curl -X POST https://youzikuaibao.com.cn/api/admin/competitor-websites \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "name": "Example Website",
    "domain": "example.com",
    "description": "网站描述",
    "monthlyVisits": "1000000",
    "globalRank": 1000,
    "tags": "标签1,标签2"
  }'

JavaScript (fetch)

fetch('https://youzikuaibao.com.cn/api/admin/competitor-websites', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
  },
  body: JSON.stringify({
    name: 'Example Website',
    domain: 'example.com',
    description: '网站描述',
    monthlyVisits: '1000000',
    createdDate: '2020-01-01',
    pagesPerVisit: 2.5,
    globalRank: 1000,
    avgDuration: '00:03:30',
    bounceRate: '45.5',
    searchTrafficRatio: '60.5',
    notes: 'Traffic.cv 数据提取',
    tags: '标签1,标签2'
  })
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    console.log(data.message);
    console.log('网站ID:', data.data.id);
  } else {
    console.error('错误:', data.error);
  }
})
.catch(error => console.error('Error:', error));

Python

import requests

url = 'https://youzikuaibao.com.cn/api/admin/competitor-websites'
headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key_here'
}
data = {
    'name': 'Example Website',
    'domain': 'example.com',
    'description': '网站描述',
    'monthlyVisits': '1000000',
    'globalRank': 1000,
    'tags': '标签1,标签2'
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result.get('success'):
    print(result.get('message'))
    print('网站ID:', result['data']['id'])
else:
    print('错误:', result.get('error'))

💡 使用说明

域名（domain）是唯一必填字段，其他字段均为可选
如果域名已存在，系统会自动更新现有记录，不会创建重复记录
支持两种认证方式：X-API-Key 请求头或 Authorization Bearer Token
monthlyVisits 支持字符串格式（如 "1,000,000"）或数字格式
avgDuration 支持 "HH:MM:SS" 格式或秒数（数字）
此接口特别适用于 Traffic.cv 浏览器插件的数据保存

API 接口文档

🔑API Key 获取

身份验证

关键词查询接口

接口地址

请求头

请求参数

响应示例

响应字段说明

错误响应

代码示例

Google趋势词查询接口

接口地址

请求头

请求参数

响应示例

响应字段说明

错误响应

代码示例

竞品网站保存接口

接口地址

请求头

请求参数

响应示例

错误响应

代码示例

💡 使用说明

更多接口