Node Api

Node API

版本： 0.5.2
状态： Phase 3 — Public
线上地址： nodeapi.ai | API 文档 | MCP

为 AI Agent 和开发者提供机器原生的空间数据处理能力。25 个端点。在 Solana 上每次操作支付 0.01 美元 USDC。无需账户、API 密钥或订阅。

---

快速入门

# 1. Send a request — get a 402 with payment details
curl -X POST https://nodeapi.ai/v1/validate \
  -F "[email protected]"

# → 402: { "recipient": "D8m8C9amSawdqSgEdXWkMZ3M86qsVQuDJswG1wZYkezP", "amount_usd": "0.01", ... }

# 2. Send 0.01 USDC to the recipient on Solana Mainnet
#    Get the transaction signature from your wallet

# 3. Retry with the transaction signature
curl -X POST https://nodeapi.ai/v1/validate \
  -F "[email protected]" \
  -H "X-PAYMENT: <your_solana_tx_signature>"

# → 200: { "total_features": 1204, "valid_count": 1204, ... }

---

付款

每个付费端点都使用 Solana 主网上的 USDC，通过 Solana Pay 付款。

协议	Solana Pay
网络	Solana 主网
资产	USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)
价格	每次操作固定收取 0.01 美元
收款方	D8m8C9amSawdqSgEdXWkMZ3M86qsVQuDJswG1wZYkezP

流程：

1. 调用任意端点 → 收到包含 Solana Pay URL 和收款方的 402
2. 在 Solana 主网上发送 0.01 USDC（附带备注：nodeapi:<operation>）
3. 使用 X-PAYMENT: <transaction_signature> 重试
4. 接收处理后的数据

---

端点

所有端点均可通过 /v1/<path>（推荐）和 /<path>（旧版，仍受支持）访问。

信息（免费）

方法	路径	描述
GET	/v1/health	服务运行状况
GET	/v1/pricing	完整价格列表

格式与检查

方法	路径	描述
POST	/v1/convert	在 GeoJSON、Shapefile、GeoPackage、KML 之间转换
POST	/v1/reproject	投影或重投影到任意 EPSG（自动检测是指定坐标系还是转换坐标系）
POST	/v1/validate	验证几何图形 — 返回 JSON 报告
POST	/v1/repair	修复无效几何图形（make_valid）
POST	/v1/schema	提取字段架构、CRS、bbox、要素数量
POST	/v1/dxf	从 DXF/CAD 文件中提取几何图形

地理处理（单个输入）

方法	路径	描述
POST	/v1/clip	按边界框或多边形掩膜裁剪
POST	/v1/buffer	按以米为单位的距离对要素进行缓冲
POST	/v1/erase	删除所有要素，保留空架构
POST	/v1/dissolve	按属性字段融合要素
POST	/v1/feature-to-point	将几何图形转换为质心点
POST	/v1/feature-to-line	将多边形边界提取为线
POST	/v1/feature-to-polygon	将闭合线转换为多边形
POST	/v1/multipart-to-singlepart	拆分多部件几何图形
POST	/v1/add-field	添加新的属性列

地理处理（两个输入）

方法	路径	描述
POST	/v1/union	合并两个图层中的所有要素
POST	/v1/intersect	对两个图层进行空间相交
POST	/v1/difference	图层 A 减去与图层 B 重叠的部分
POST	/v1/append	将图层 B 的要素追加到图层 A 的架构中
POST	/v1/merge	合并两个图层并保留所有字段
POST	/v1/spatial-join	按空间关系连接属性

瓦片

方法	路径	描述
POST	/v1/vectorize	生成 .mbtiles 矢量瓦片包（tippecanoe）

任务

方法	路径	描述
GET	/v1/jobs/{id}	轮询异步任务状态
GET	/v1/jobs/{id}/download	下载已完成的任务结果

支持的输入格式： GeoJSON、Shapefile (.zip)、GeoPackage (.gpkg)、KML、GDB（读取）、DXF

---

MCP 集成

Node API 将全部 25 个端点作为 MCP 工具提供 — 兼容 Claude、GPT-4o 以及任何支持 MCP 的 Agent。

远程（无需安装）

https://nodeapi.ai/mcp/sse

将任意 MCP 客户端连接到此 SSE 端点。无需身份验证。

Claude Desktop（本地）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "node-api": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "app.mcp_server"],
      "cwd": "/path/to/node-api"
    }
  }
}

**22 个 MCP 工具：**转换、重投影、验证、修复、模式、裁剪、DXF、缓冲区、合并、相交、差集、擦除、融合、要素转点、要素转线、要素转面、多部件转单部件、添加字段、追加、合并、空间连接、定价

---

Webhook

对于异步作业（DXF 转换、任何大型文件），传入 webhook_url，即可在作业完成时接收 POST，而无需轮询。

curl -X POST https://nodeapi.ai/v1/dxf \
  -F "[email protected]" \
  -F "output_format=geojson" \
  -F "webhook_url=https://your-agent.com/callback" \
  -H "X-PAYMENT: <tx_signature>"

Webhook 负载：

{
  "job_id": "abc-123",
  "operation": "dxf",
  "status": "done",
  "result_url": "https://nodeapi.ai/v1/jobs/abc-123/download",
  "result_filename": "output.geojson",
  "size_bytes": 48291
}

使用 X-Webhook-Signature: sha256=<HMAC> 签名以供验证。

---

架构

• FastAPI — 异步，OpenAPI 规范位于 /docs
• GeoPandas + GDAL — 支持 200 多种矢量格式
• Shapely 2.x — 几何运算
• pyproj — CRS 重投影
• tippecanoe 2.79 — 矢量瓦片生成
• PostgreSQL — 操作日志 + 作业队列
• Solana Pay — Solana 主网上的 USDC 小额支付
• MCP SDK — stdio（本地）+ SSE（远程）传输
• Cloudflare Tunnel — nodeapi.ai → API 服务

---

开发环境设置

git clone https://github.com/eianray/node-api
cd node-api
python3 -m venv venv
venv/bin/pip install -r requirements.txt
cp .env.example .env
# Leave SOLANA_WALLET_ADDRESS=YOUR_SOLANA_WALLET_ADDRESS for dev mode (bypasses payment)
venv/bin/uvicorn app.main:app --reload --port 8100

---

路线图

• 阶段 1 ✅ — 转换、重投影、验证、修复、模式、裁剪
• 阶段 2 ✅ — DXF/CAD、缓冲区、拓扑（合并/相交/差集）、远程 MCP SSE
• 阶段 3 ✅（2026 年 3 月 4 日） — 新增 11 个地理处理端点、Solana Pay、Webhook、矢量瓦片、API 版本控制、22 个 MCP 工具
• 阶段 4 — 迁移至 Hetzner、CDN 缓存、批处理 API、Agent 目录列表

---

nodeapi.ai — 面向 Agent 经济的空间处理基础设施。