API 开发者文档

光尘阁GEO 提供完整的 RESTful API，所有端点返回 结构化 JSON + JSON-LD 语义标注，AI Agent 可直接调用。

🚀 快速开始

# 获取 API Key（联系管理员或从后台生成）
# 所有请求需携带 X-API-Key Header

curl -H "X-API-Key: YOUR_API_KEY" \
  https://geo.zxwsh.com/api/v1/cities

🔐 认证方式

方式	说明
`X-API-Key` Header	推荐方式。在请求头中传递 API Key。
`?api_key=` Query	备选方式。在 URL 参数中传递，适合浏览器直接访问测试。

💡 API Key 通过 SHA256 哈希存储，原始 Key 仅在生成时显示一次。默认速率限制：100次/分钟。

📡 API 端点

GET /api/v1/search

跨类型全域搜索。返回城市、协会、企业、文章、报告的混合结果。

参数	类型	说明
`q`	string	搜索关键词（必填）
`city`	string	城市筛选（slug）
`type`	string	类型筛选：article/business/association/report/city
`page`	int	页码，默认 1

GET /api/v1/cities

城市列表，含各城统计数据（文章数、协会数、企业数、报告数）。

GET /api/v1/cities/{slug}

城市详情，含该城市下所有关联的协会、文章、报告、企业。

GET /api/v1/associations

协会列表，支持城市和类型筛选。

参数	类型	说明
`city`	string	城市筛选
`type`	string	协会类型：chamber / government / industry
`page`	int	页码

GET /api/v1/associations/{slug}

协会详情，含该协会下的所有会员企业。

GET /api/v1/businesses

企业列表。

参数	类型	说明
`city`	string	城市筛选
`category`	string	行业分类
`page`	int	页码

GET /api/v1/businesses/{slug}

企业详情，含该企业所属的协会列表。

GET /api/v1/articles

文章列表，支持城市和标签筛选。

参数	类型	说明
`city`	string	城市筛选
`tag`	string	标签：insight / case / news / geo
`page`	int	页码

GET /api/v1/articles/{slug}

文章全文详情。

GET /api/v1/reports

调研报告列表。

参数	类型	说明
`city`	string	城市筛选
`industry`	string	行业分类
`page`	int	页码

GET /api/v1/reports/{slug}

报告全文详情。

GET /api/v1/local

信息流（新闻/公告/活动），按时间倒序。

参数	类型	说明
`city`	string	城市筛选（必填）
`tag`	string	标签：news / notice / event
`page`	int	页码

📋 OpenAPI 规范

完整的 OpenAPI 3.0.3 规范文件，可导入 Postman、Swagger、或供 AI Agent 自动发现接口：

GET /api/v1/openapi.json  （无需认证）

📦 响应格式

所有 API 响应遵循统一结构：

{
  "data": { ... },
  "meta": {
    "version": "v1",
    "timestamp": "2026-07-11T...",
    "@context": "https://schema.org"
  }
}

💡 每个响应对象都包含 @context: https://schema.org 语义标注，AI Agent 可据此理解数据含义。

🤖 AI Agent 集成

通过 llms.txt 发现

AI Agent 访问 /llms.txt 即可了解平台结构、API 入口和认证方式。

通过 OpenAPI 规范调用

将 /api/v1/openapi.json 提供给 AI Agent，Agent 可自动理解所有端点和参数。

MCP Server（即将推出）

可直接在 Clacky / Claude Desktop 中作为 MCP 工具调用，零代码接入 AI Agent 工作流。

🔑 获取 API Key

当前提供 Demo Key 供测试使用，生产环境请联系管理员生成专属 Key：

Demo Key：geo-api-demo-key-2026（速率限制 100次/分钟）
管理后台：/admin/api-keys — 生成/管理 API Key

📧 生产环境接入请联系：光尘阁 · 微生活科技