Швидкий старт API астрології: TypeScript і Python за 5 хвилин

🕓 Запис від 2026-04-14, оновлено 2026-05-09. TS / Python / PHP SDK тепер живуть на public registries — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Деталі в changelog.

Ти хочеш порахувати натальну карту з коду. Ось найкоротший шлях — за 5 хвилин від нуля до робочого JSON.

Крок 1: Отримай API-ключ (30 секунд)

Зареєструйся на api.astroway.info/dashboard/sign-up. Безкоштовний план: 10 000 кредитів / місяць. Без картки.

У dashboard натисни «Create key» → «Production» → скопіюй. Ключі мають вигляд aw_live_aB3xY7pQ9rN2mK4jH8vC5tL6wZ1fD0eR.

Підказка: є також sandbox-ключі з префіксом aw_test_ — вони не списують кредити. Використовуй їх під час розробки.

Крок 2: Встанови SDK

TypeScript

npm install @astroway/sdk

Python

pip install astroway

Обидва SDK покривають усі 705 ендпоінт із типізованими запитами й відповідями.

Крок 3: Перша натальна карта

TypeScript

import { Astroway } from '@astroway/sdk';

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

const chart = await client.chart({
  date: '1990-07-14',
  time: '14:30:00',
  timezoneOffset: 3,      // UTC+3, літо в Києві
  latitude: 50.4501,
  longitude: 30.5234,
  houseSystem: 'P',       // Placidus
});

console.log(`Sun: ${chart.planets[0].sign} at ${chart.planets[0].longitude}°`);
console.log(`ASC: ${chart.houses.ascendant}°`);
console.log(`Aspects: ${chart.aspects.length}`);

Запусти:

ASTROWAY_API_KEY=aw_live_... npx tsx chart.ts

Python

from astroway import Astroway

client = Astroway(api_key="aw_live_your_key_here")

chart = client.chart(
    date="1990-07-14",
    time="14:30:00",
    timezone_offset=3,
    latitude=50.4501,
    longitude=30.5234,
    house_system="P",
)

print(f"Sun: {chart['planets'][0]['sign']} at {chart['planets'][0]['longitude']}°")
print(f"ASC: {chart['houses']['ascendant']}°")
print(f"Aspects: {len(chart['aspects'])}")

Запусти:

ASTROWAY_API_KEY=aw_live_... python3 chart.py

Що повертає API

Назад приходить JSON-об’єкт із чотирма основними частинами:

planets

Масив із 12 об’єктів (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, North Node, Chiron):

{
  "name": "Sun",
  "longitude": 111.87,      // еклiптична довгота у градусах
  "latitude": 0.0,
  "speed": 0.955,           // градусів на день (від'ємне = ретроград)
  "sign": "cancer",
  "signIndex": 3,
  "house": 10,
  "retrograde": false
}

houses

Куспіди домів (12 штук), а також asc і MC:

{
  "system": "P",
  "cusps": [12.34, 43.21, ...],   // 12 значень
  "ascendant": 12.34,
  "mc": 280.12
}

aspects

Масив аспектів між планетами:

{
  "planet1": "Sun",
  "planet2": "Moon",
  "type": "sextile",        // conjunction, opposition, trine, square, sextile, quincunx
  "orb": 1.36,              // відхилення від точного у градусах
  "applying": true
}

chartSect

"diurnal" (Сонце над горизонтом у момент народження) або "nocturnal" (під горизонтом). Використовується в класичній астрології.

Що далі

Що ще спробувати:

Синастрія — сумісність двох людей:

const synastry = await client.synastry({
  chart1: { date: '1990-07-14', time: '14:30:00', timezoneOffset: 3, latitude: 50.45, longitude: 30.52 },
  chart2: { date: '1992-03-22', time: '09:15:00', timezoneOffset: 2, latitude: 48.85, longitude: 2.35 },
});
console.log(`Compatibility score: ${synastry.compatibility.score}/100`);

Поточні транзити на натальну карту:

const transits = await client.transits({
  // дані народження
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.4501, longitude: 30.5234,
  // дата транзиту
  transitDate: '2026-04-14',
});

Щоденний гороскоп із реальних транзитів:

const horoscope = await client.horoscopeDaily({
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.4501, longitude: 30.5234,
});
console.log(horoscope.text);

Повна Human Design карта:

const hd = await client.humanDesign({
  date: '1990-07-14', time: '14:30:00', timezoneOffset: 3,
  latitude: 50.4501, longitude: 30.5234,
});
console.log(`${hd.type} — ${hd.strategy} — Profile ${hd.profile}`);

Вартість у кредитах

Натальна карта (/chart): 20 кредитів
Синастрія: 50 кредитів
Транзити: 50 кредитів
Щоденний гороскоп: 20 кредитів
Human Design: 50 кредитів

Безкоштовний план: 10 000 кредитів / місяць = 500 натальних карт, або 200 синастрій, або змішане навантаження.

Обробка помилок

Кожна відповідь містить заголовки з кредитами:

X-Credits-Used: 20
X-Credits-Remaining: 4980
X-Credits-Reset: 2026-05-01T00:00:00Z

Коли кредити закінчуються — отримаєш 402 Payment Required. Коли вдариш по rate-limit’у (Free: 10 запитів / хв) — 429 Too Many Requests із заголовком Retry-After.

SDK кидає типізовані помилки, які можна ловити:

try {
  const chart = await client.chart({ ... });
} catch (err) {
  if (err.code === 'credits_exhausted') {
    console.log('Upgrade plan or wait for reset');
  } else if (err.code === 'rate_limit_exceeded') {
    console.log(`Retry in ${err.retryAfter} seconds`);
  }
}

І на цьому все

Тепер у тебе є:

Робочий API-ключ
Встановлений SDK
Перша натальна карта
Достатньо прикладів, щоб додати синастрію, транзити, гороскопи

Читати далі:

Повний путівник «з чого почати» — більше деталей
Приклад: натальна карта — глибший walkthrough
API reference — усі 705 ендпоінт

AstroWay team

Інженерна команда AstroWay API. Ми загортаємо Swiss Ephemeris у чистий REST і пишемо про нудні деталі, які насправді важливі.

// побудуй на цьому

Той самий Swiss Ephemeris, що й у Solar Fire — у 4 рядках коду.

Безкоштовний ключ без картки. 5 000 викликів на місяць до першої оплати.

Отримати API-ключ → Документація

Швидкий старт API астрології: TypeScript і Python за 5 хвилин

Крок 1: Отримай API-ключ (30 секунд)

Крок 2: Встанови SDK

TypeScript

Python

Крок 3: Перша натальна карта

TypeScript

Python

Що повертає API

planets

houses

aspects

chartSect

Що далі

Вартість у кредитах

Обробка помилок

І на цьому все

Той самий Swiss Ephemeris, що й у Solar Fire — у 4 рядках коду.

Більше з блогу усі дописи →

Як збудувати астрологічний застосунок: повний путівник для розробника

Human Design API: будуй HD-застосунки на 12 ендпоінтах

Додай астрологію до свого AI-агента через MCP