SDK 接入文档

SDK 使用总览

官方 SDK 封装了底层 HTTP 调用、鉴权与数据结构，你只需要传入业务参数即可拿到带类型的结果。当前最新版本为 v1.1.0（Node / Python / Java），已支持星座·运势、星盘·合盘、国学·命理、国学·术数等多条产品线的核心接口。推荐在服务端或受信任的后端环境中使用 SDK，在前端页面中仅调用你自己的后端接口，避免泄露密钥。

通用使用步骤

在控制台中获取 App ID / App Key。
在项目中安装对应语言的 SDK 依赖。
使用 App ID / App Key 初始化客户端。
调用 SDK 中的业务方法（如本命盘、关系盘等），直接获取解析好的结果。

Node SDK：项目地址与使用

适用于基于 Node.js / TypeScript 的服务端项目，如 API 网关、后端服务等。

项目地址：

Gitee： https://gitee.com/wingerd/apiworks-astro-node-sdk

GitHub： https://github.com/8haoNetwork/apiworks-astro-node-sdk

安装方式：

npm install apiworks-astro-node-sdk
# 或者
pnpm add apiworks-astro-node-sdk

运行环境与依赖要求：

- Node.js >= 14
- axios >= 1.6
- zod >= 3.22

调用示例

JavaScript：

const { AstroCloudClient } = require('apiworks-astro-node-sdk')

// 创建客户端
const client = new AstroCloudClient({
  app_id: 'your-app-id',
  app_key: 'your-app-key'
})

// 本命盘
async function getNatalChart() {
  try {
    const resp = await client.chart_natal({
      birth_dt: '1990-08-14 12:00:00',
      tz: 8,
      longitude: 116.4074,
      latitude: 39.9042
    })
    
    if (resp.code === 0 && resp.data) {
      console.log(resp.data.house, resp.data.planet)
    }
  } catch (error) {
    console.error('Error:', error)
  }
}

getNatalChart()

TypeScript：

import { AstroCloudClient, SinglePointQry, ApiResp, AstroDataVo } from 'apiworks-astro-node-sdk'

// 创建客户端
const client = new AstroCloudClient({
  app_id: 'your-app-id',
  app_key: 'your-app-key'
})

// 本命盘
async function getNatalChart() {
  try {
    const qry: SinglePointQry = {
      birth_dt: '1990-08-14 12:00:00',
      tz: 8,
      longitude: 116.4074,
      latitude: 39.9042
    }
    
    const resp: ApiResp<AstroDataVo> = await client.chart_natal(qry)
    
    if (resp.code === 0 && resp.data) {
      console.log(resp.data.house, resp.data.planet)
    }
  } catch (error) {
    console.error('Error:', error)
  }
}

getNatalChart()

Python SDK：项目地址与安装

适用于基于 Python 的后端服务，如 Django / FastAPI / Flask 等。

项目地址：

Gitee： https://gitee.com/wingerd/apiworks-astro-py-sdk

GitHub： https://github.com/8haoNetwork/apiworks-astro-py-sdk

安装方式：

pip install astro-apiworks-sdk

运行环境与依赖要求：

- Python >= 3.10
- httpx >= 0.27
- pydantic >= 2.0

调用示例

同步客户端：

from apiworks_astro_sdk import AstroCloudClient, SinglePointQry, TimeAndLocation

client = AstroCloudClient(
    app_id="your-app-id",
    app_key="your-app-key",
)

# 本命盘
qry = SinglePointQry(
    birth_dt="1990-08-14 12:00:00",
    tz=8,
    longitude=116.4074,
    latitude=39.9042,
)
resp = client.chart_natal(qry)  # ApiResp[AstroDataVo]，强类型
if resp.code == 0 and resp.data:
    print(resp.data.house, resp.data.planet)

异步客户端：

import asyncio
from apiworks_astro_sdk import AsyncAstroCloudClient, ScopeQryReq, TimeAndLocation, ScopeRespVo

async def main():
    client = AsyncAstroCloudClient(
        app_id="your-app-id",
        app_key="your-app-key",
    )
    qry = ScopeQryReq(
        birth_point=TimeAndLocation(
            birth_dt="1990-01-01 12:00:00", tz=8, longitude=116.4, latitude=39.9
        ),
        transit_point=TimeAndLocation(
            birth_dt="2025-02-26 12:00:00", tz=8, longitude=116.4, latitude=39.9
        ),
    )
    resp = await client.scope_day("user-123", qry)  # ApiResp[ScopeRespVo]
    if resp.code == 0 and resp.data:
        scope: ScopeRespVo = resp.data
        print(scope.scope_total, scope.scope_info)

asyncio.run(main())

Java SDK：项目地址与安装

适用于 Spring Boot 等 Java 后端项目。

项目地址：

Gitee： https://gitee.com/wingerd/apiworks-astro-java-sdk

GitHub： https://github.com/8haoNetwork/apiworks-astro-java-sdk

安装方式：

在你的 pom.xml 中添加：

<dependency>
    <groupId>com.apiworks</groupId>
    <artifactId>apiworks-astro-java-sdk</artifactId>
    <version>1.1.0</version>
</dependency>

调用示例

同步客户端：

import com.apiworks.astro.AstroCloudClient;
import com.apiworks.astro.model.common.ApiResp;
import com.apiworks.astro.model.common.TimeAndLocation;
import com.apiworks.astro.model.requests.chart.SinglePointQry;
import com.apiworks.astro.model.responses.astro.AstroDataVo;

public class Demo {
    public static void main(String[] args) {
        AstroCloudClient client = new AstroCloudClient(
                "your-app-id",
                "your-app-key"
        );

        SinglePointQry qry = new SinglePointQry(
                new TimeAndLocation("1990-08-14 12:00:00", 8, 116.4074, 39.9042)
        );

        ApiResp<AstroDataVo> resp = client.chartNatal(qry);
        if (resp.getCode() == 0 && resp.getData() != null) {
            AstroDataVo data = resp.getData();
            // 访问 data.getPlanet() / data.getHouse() 等字段
            System.out.println(data);
        }
    }
}

异步客户端：

import com.apiworks.astro.AsyncAstroCloudClient;
import com.apiworks.astro.model.common.ApiResp;
import com.apiworks.astro.model.common.TimeAndLocation;
import com.apiworks.astro.model.requests.chart.SinglePointQry;
import com.apiworks.astro.model.responses.astro.AstroDataVo;

import java.util.concurrent.CompletableFuture;

public class AsyncDemo {
    public static void main(String[] args) throws Exception {
        AsyncAstroCloudClient client = new AsyncAstroCloudClient(
                "your-app-id",
                "your-app-key"
        );

        SinglePointQry qry = new SinglePointQry(
                new TimeAndLocation("1990-08-14 12:00:00", 8, 116.4074, 39.9042)
        );

        CompletableFuture<ApiResp<AstroDataVo>> future = client.chartNatal(qry);
        future.thenAccept(resp -> {
            if (resp.getCode() == 0 && resp.getData() != null) {
                System.out.println("planet size = " + resp.getData().getPlanet().size());
            } else {
                System.out.println("code=" + resp.getCode() + ", msg=" + resp.getMsg());
            }
        }).exceptionally(ex -> {
            ex.printStackTrace();
            return null;
        });

        // 简单等待异步完成
        Thread.sleep(5000);
    }
}