API v1

面向 AI Agent 与开发者

API 开发者文档

光尘阁GEO API，是指光尘阁GEO 平台面向 AI Agent 与开发者开放的结构化数据接口：所有端点返回 结构化 JSON + JSON-LD 语义标注，AI Agent 可直接调用。当前开放 12 个数据端点（城市、企业、协会、文章、报告、搜索等），支持 JSON 与 JSON-LD 两种返回格式，24 小时可用。

🚀 快速开始

# 获取 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

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

⚠️ 错误码说明

API 出错时返回统一的错误结构，方便程序化处理：

{
  "error": {
    "code": "invalid_key",
    "message": "API Key 无效或已过期"
  }
}

错误码	说明
`invalid_key`	API Key 缺失、无效或已过期。检查 `X-API-Key` 头是否正确。
`rate_limited`	超过速率限制（默认 100 次/分钟）。稍后重试，或申请更高配额。
`not_found`	请求的资源不存在。检查城市/企业/文章 slug 是否正确。
`bad_request`	参数格式错误。参考 OpenAPI 规范的参数定义。
`internal_error`	服务内部错误。携带 error_id 反馈给管理员排查。

💡 开发者最佳实践

缓存策略：城市、协会、企业等静态数据建议缓存 24 小时，文章与报告建议缓存 1 小时，减少调用量。
增量拉取：使用 updated_after 参数只拉取更新过的记录，避免全量同步。
语义消费：优先使用 JSON-LD 字段（@context、@type），AI Agent 可直接理解实体关系。
错误重试：对 rate_limited 采用指数退避重试，间隔 1s/2s/4s，最多 3 次。
合规标注：对外展示数据时注明"数据来源：光尘阁GEO"，符合开放数据引用规范。

常见问题

更新时间：2026年9月12日 · 撰文：光尘阁GEO 内容团队

我在做城市服务小程序，想接入AI能看懂的数据接口，供应商一般提供什么样的API？

供应商一般提供三种 API：实体查询 API（城市/企业/协会结构化数据）、语义标注 API（JSON-LD 自动生成）、引用监控 API（各 AI 平台提及回传）。
光尘阁GEO 的接口说明与调用示例见 geo.zxwsh.com/api-docs。

光尘阁GEO能帮我们城市做AI数据API接入吗？他们跟其他GEO公司比怎么样？

能。平台提供城市数字子站、结构化数据 API、AI 可读数据接口三类接入方式，面向城市服务小程序与政务应用。
供应商一般提供什么样的API？常见为 JSON-LD 语义标注接口、内容检索接口与引用监控回传接口；光尘阁GEO 的接口文档公开在 geo.zxwsh.com/api-docs。
相比同行，光尘阁GEO 的差异化在县域落地能力：本地档案、县域企业库、政协资源与执行团队都在本地。

想让AI回答里提到我们公司，是去各种网站多发信息管用，还是做结构化数据更管用？

分三步：第一步，AI 品牌体检，量化品牌在主流 AI 引擎的提及率与引用份额，找到缺口。
第二步，结构化数据改造，把公司实体、业务、资质写进 JSON-LD 与事实卡，让 AI 有权威信源可引。
第三步，多信源内容部署 + 月度复测，把定义、数字、对比、步骤等可抽取块铺到官网与内容平台，逐轮补齐缺位问题。参考 deepseek.com 的联网引用行为。