Back to Docs
SDKs

Official SDKs

Client libraries for TypeScript, Python, Go, PHP, Rust, .NET and Dart. Each one is generated from the public OpenAPI document, so every endpoint in these docs has a method with typed requests and responses. They all handle authentication, errors and retries the same way.

Languages

TypeScript

On npm
@freeastroapi/sdk

Node.js 18 or later

npmSource on GitHub

Python

On PyPI
freeastroapi

Python 3.11 or later, sync and async clients

PyPISource on GitHub

Go

On pkg.go.dev
github.com/GabrielRw/freeastroapi-go-sdk

Go 1.24 or later

pkg.go.devSource on GitHub

PHP

On Packagist
freeastroapi/sdk

Any PSR-18 HTTP client, Guzzle suggested

PackagistSource on GitHub

Rust

On crates.io
freeastroapi

Rust 1.85 or later, async with Tokio

crates.ioSource on GitHub

.NET

NuGet release soon
FreeAstroApi.Sdk

.NET 8, .NET 10 and .NET Standard 2.0

Source on GitHub

Dart & Flutter

pub.dev release soon
freeastroapi

Dart 3.4 or later (Flutter 3.22 or later)

Source on GitHub

Quick start

Install

npm install @freeastroapi/sdk

First request

import { FreeAstro } from "@freeastroapi/sdk";

const client = new FreeAstro({
  apiKey: process.env.FREEASTRO_API_KEY!,
});

const cities = await client.geo.search({ q: "Paris", limit: 3 });
console.log(cities.results[0]?.timezone); // Europe/Paris

const chart = await client.natal.calculate({
  year: 1990, month: 6, day: 15, hour: 14, minute: 30, city: "Paris",
});

Load the key from an environment variable or secret store. The Go, PHP, Rust and .NET SDKs read FREEASTRO_API_KEY on their own when you don't pass one. Get a key from the dashboard. The TypeScript README covers every option, error type and more examples.

Every endpoint, typed

Methods follow the API paths, so /api/v2/vedic/panchang becomes client.vedic.panchang. Requests and responses use the schemas from the OpenAPI document.

Tolerant parsing

Responses are decoded leniently. A new field or enum value added to the API won't break an app built on an older SDK version.

Kept in sync

Each repository checks the published API spec daily and regenerates the client when it changes, with contract tests against a mock of the spec.

Retries

All SDKs share one retry policy. Failed requests are retried up to 2 times, with exponential backoff starting at 0.5 seconds, full jitter and a cap of 8 seconds.

  • 429 Too Many Requests is always retried, after the Retry-After delay. If that delay is longer than 30 seconds, the SDK raises a rate-limit error that carries the delay instead of waiting. See rate limits.
  • 408, 500, 502, 503, 504, timeouts and network errors are retried, except on the operations below.
  • Other 4xx errors are never retried.

These operations can create a report job or consume AI credits, so a server error is retried only when you send an Idempotency-Key or opt in for that request:

  • POST /api/v1/natal/calculate
  • POST /api/v1/ai/generate
  • POST /api/v2/vedic/chat
  • POST /api/v2/western/chat
  • POST /api/v2/vedic/qa
  • POST /api/v1/western/transits/timeline
  • POST /api/v1/western/transits/insights

Another language?

The SDKs are generated from the public OpenAPI 3.1 document at https://api.freeastroapi.com/openapi.json. Point any OpenAPI generator at it to build a client for a language not listed here, or call the REST API directly as shown in the rest of these docs. For AI tools, use the hosted MCP server.

Keep API keys on servers and other trusted runtimes. Don't ship them in browser bundles, mobile apps or desktop apps.