Client-Bibliotheken

Helper herunterladen — PHP, Python, JavaScript

Drei kleine Helfer-Klassen, die das Boilerplate (curl/fetch + JSON + Auth-Header) wegnehmen. Keine Composer/pip/npm-Abhaengigkeit — Datei einbinden und losrechnen. Ein Aufruf pro Endpunkt; bei HTTP-Fehlern fliegt eine typisierte Exception. Du behaeltst die volle API-Kontrolle ueber den generischen request()- Aufruf, falls neue Endpunkte hinzukommen.

Download

PHP PHP 8.1+ · ext-curl + ext-json

`astroapi-client.php`

Klasse AstroApiClient, Exception AstroApiException. Kein Namespace, kein Composer — einmal require und fertig.

Datei herunterladen

Python Python 3.9+ · nur stdlib

`astroapi_client.py`

Klasse AstroApiClient, Exception AstroApiException. Keine externen Abhaengigkeiten — urllib + json reichen.

Datei herunterladen

JavaScript Node 18+ oder Browser

`astroapi-client.js`

UMD-Bundle: require(), import oder <script>-Tag. Nutzt fetch (Browser + Node 18+).

Datei herunterladen

Lizenz: MIT. Du darfst die Dateien beliebig anpassen, einbetten, unter eigenem Namen weitergeben.

Vorher / Nachher

Beispiel POST /v1/radix in PHP:

Ohne Helper

<?php
$ch = curl_init('https://astroapi.services/v1/radix');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ak_test_<DEIN_KEY>',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'birth' => [
        'datetime' => '2026-04-20T12:00:00Z',
        'location' => ['latitude' => 52.52, 'longitude' => 13.41],
    ],
]));
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Mit Helper

<?php
require 'astroapi-client.php';
$api = new AstroApiClient('ak_test_<DEIN_KEY>');
$response = $api->radix([
    'birth' => [
        'datetime' => '2026-04-20T12:00:00Z',
        'location' => ['latitude' => 52.52, 'longitude' => 13.41],
    ],
]);

Erste Schritte

Den jeweiligen Helper herunterladen, in dein Projekt legen und mit require / import einbinden. Dann eine Instanz mit deinem API-Key bauen — die typisierten Endpunkt-Methoden sind benannt nach den Routen (radix, transits, lots, mercuryReturn, ...). Pro Methode einmalig den Body als Array/Dict uebergeben — das war's.

<?php
require 'astroapi-client.php';

$api = new AstroApiClient('ak_test_<DEIN_KEY>');

// Radix berechnen
$radix = $api->radix([
    'birth' => [
        'datetime' => '1980-05-17T14:32:00',
        'timezone' => 'Europe/Berlin',
        'location' => ['latitude' => 52.52, 'longitude' => 13.405],
    ],
    'options' => ['house_system' => 'koch'],
]);
print_r($radix);

// Transite zum Geburtsbild
$tr = $api->transits([
    'natal' => [
        'datetime' => '1980-05-17T14:32:00',
        'timezone' => 'Europe/Berlin',
        'location' => ['latitude' => 52.52, 'longitude' => 13.405],
    ],
    'at' => '2026-04-20T12:00:00Z',
]);

import { AstroApiClient } from './astroapi-client.js';

const api = new AstroApiClient('ak_test_<DEIN_KEY>');

// Radix berechnen
const radix = await api.radix({
  birth: {
    datetime: '1980-05-17T14:32:00',
    timezone: 'Europe/Berlin',
    location: { latitude: 52.52, longitude: 13.405 }
  },
  options: { house_system: 'koch' }
});
console.log(radix.chart.planets.sun);

// Transite zum Geburtsbild
const tr = await api.transits({
  natal: {
    datetime: '1980-05-17T14:32:00',
    timezone: 'Europe/Berlin',
    location: { latitude: 52.52, longitude: 13.405 }
  },
  at: '2026-04-20T12:00:00Z'
});

from astroapi_client import AstroApiClient

api = AstroApiClient('ak_test_<DEIN_KEY>')

# Radix berechnen
radix = api.radix({
    'birth': {
        'datetime': '1980-05-17T14:32:00',
        'timezone': 'Europe/Berlin',
        'location': {'latitude': 52.52, 'longitude': 13.405},
    },
    'options': {'house_system': 'koch'},
})
print(radix['chart']['planets']['sun'])

# Transite zum Geburtsbild
tr = api.transits({
    'natal': {
        'datetime': '1980-05-17T14:32:00',
        'timezone': 'Europe/Berlin',
        'location': {'latitude': 52.52, 'longitude': 13.405},
    },
    'at': '2026-04-20T12:00:00Z',
})

Fehlerbehandlung

Bei HTTP-Status ≥ 400 wirft der Helper eine AstroApiException mit dem Fehler-Code und -Text aus dem API-Response-Body. Status und decodierter Fehler-Body sind ebenfalls verfuegbar.

<?php
try {
    $r = $api->radix(['birth' => [/* ... */]]);
} catch (AstroApiException $e) {
    fwrite(STDERR, 'API-Fehler ' . $e->status . ': ' . $e->getMessage() . PHP_EOL);
    if ($e->body !== null) {
        var_dump($e->body['error']);
    }
}

import { AstroApiClient, AstroApiException } from './astroapi-client.js';

try {
  const r = await api.radix({ birth: { /* ... */ } });
} catch (e) {
  if (e instanceof AstroApiException) {
    console.error(`API-Fehler ${e.status}: ${e.message}`);
    if (e.body) console.error(e.body.error);
  } else throw e;
}

from astroapi_client import AstroApiClient, AstroApiException

try:
    r = api.radix({'birth': {...}})
except AstroApiException as e:
    print(f'API-Fehler {e.status}: {e}')
    if e.body is not None:
        print(e.body['error'])

Generischer Aufruf fuer eigene/neue Endpunkte

Falls die API-Referenz schneller waechst als die Helper, oder du einen Endpunkt brauchst, fuer den keine typisierte Methode existiert: request() akzeptiert Methode + Pfad + Body + Query-Parameter direkt.

<?php
$me   = $api->request('GET',  '/v1/me');
$cust = $api->request('POST', '/v1/some-future-endpoint', ['foo' => 'bar']);

const me   = await api.request('GET',  '/v1/me');
const cust = await api.request('POST', '/v1/some-future-endpoint', { foo: 'bar' });

me   = api.request('GET',  '/v1/me')
cust = api.request('POST', '/v1/some-future-endpoint', {'foo': 'bar'})

Was die Helper nicht tun

Kein Caching — die ETag-Header sind sichtbar im Response, du entscheidest selbst, ob und wie du sie nutzt (siehe Auth & Limits).
Keine Retry-Logik — bei 429 kommt eine Exception mit Retry-After-Header im Response-Body.
Keine Schema-Validation der Bodies — der API-Server validiert serverseitig und liefert klare Fehler-Codes (invalid_input, missing_field usw.).

Wenn du eines davon brauchst, kannst du den Helper trivial erweitern oder den generischen request()-Aufruf in eine eigene Wrapper-Klasse stecken.