astroAPI — POST /v1/returns

Beschreibung

Findet den/die naechsten Zeitpunkt/e, an denen der/die Transitkoerper die Radix-Laenge (plus optionalem target_angle) wieder erreichen. Optional wird fuer jedes Return ein komplettes Chart am Return-Ort berechnet (Planeten, Haeuser, Aspekte). Retrograde Mehrfachreturns werden fuer alle Koerper mit Retro-Schleifen korrekt aufgeloest (letzte direkte Kreuzung des Clusters).

Parameter

Name	In	Typ	Pflicht	Beschreibung
`natal`	body	object	nein	{ datetime, timezone, location } — API berechnet Radix-Planetenlaengen selbst.
`natal_positions`	body	object	nein	Vorberechnete Radix-Laengen. Dann ist "location" Pflicht (Return-Chart-Ort).
`planet`	body	mixed	ja	String oder Array. Moegliche Werte: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, chiron, pholus, ceres, pallas, juno, vesta, mean_node, mean_apogee (Knoten-/Lilith-Wiederkehr).
`target_angle`	body	number	nein	Winkel-Offset zur Natal-Laenge in Grad (0..360). 0 = klassischer Return (Default), 180 = Demi-Return, 90/270 = Quartal-Returns.
`from`	body	string	nein	ISO 8601. Startpunkt der Suche. Default: aktueller Zeitpunkt (UTC).
`count`	body	integer	nein	Anzahl Returns pro Planet. Default 1, Maximum 50.
`location`	body	object	nein	Ort fuer das Return-Chart. Default: Geburtsort (wenn "natal" uebergeben wurde).
`include`	body	array	nein	Teilmenge von ["chart","houses","aspects"] (Default: alle drei) plus optional "crossings". Mit "crossings" liefert jedes Return zusaetzlich alle Kreuzungen seines Clusters — bei rueckläufigen Returns der volle Dreifachdurchgang (direkt→retrograd→direkt); der oben gemeldete Termin ist die LETZTE davon. "crossings" ist additiv und NICHT im Default enthalten.
`house_system`	body	string	nein	Haeusersystem fuer das Return-Chart. Default "koch".
`aspects`	body	object	nein	{ orbs, aspect_types, aspects } — wie bei /v1/radix.

Beispiel-Aufruf

Variante: Direkter HTTP-Aufruf, keine Abhaengigkeit.

curl -sS \
  -H "X-API-Key: ak_test_<DEIN_KEY>" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "natal": {
        "datetime": "1980-05-17T14:32:00",
        "timezone": "Europe/Berlin",
        "location": {
            "latitude": 52.52,
            "longitude": 13.405
        }
    },
    "planet": [
        "sun",
        "jupiter"
    ],
    "from": "2026-01-01T00:00:00Z",
    "count": 1,
    "include": [
        "chart",
        "houses",
        "aspects"
    ]
}' \
  "https://astroapi.services/v1/returns"

<?php
$ch = curl_init("https://astroapi.services/v1/returns");
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, '{"natal":{"datetime":"1980-05-17T14:32:00","timezone":"Europe/Berlin","location":{"latitude":52.52,"longitude":13.405}},"planet":["sun","jupiter"],"from":"2026-01-01T00:00:00Z","count":1,"include":["chart","houses","aspects"]}');
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($response);

<?php
require 'astroapi-client.php';
$api = new AstroApiClient('ak_test_<DEIN_KEY>');
$response = $api->returns([
    'natal' => [
        'datetime' => '1980-05-17T14:32:00',
        'timezone' => 'Europe/Berlin',
        'location' => [
            'latitude' => 52.52,
            'longitude' => 13.405,
        ],
    ],
    'planet' => [
        'sun',
        'jupiter',
    ],
    'from' => '2026-01-01T00:00:00Z',
    'count' => 1,
    'include' => [
        'chart',
        'houses',
        'aspects',
    ],
]);
print_r($response);

const response = await fetch('https://astroapi.services/v1/returns', {
  method: 'POST',
  headers: { 'X-API-Key': 'ak_test_<DEIN_KEY>', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "natal": {
        "datetime": "1980-05-17T14:32:00",
        "timezone": "Europe/Berlin",
        "location": {
            "latitude": 52.52,
            "longitude": 13.405
        }
    },
    "planet": [
        "sun",
        "jupiter"
    ],
    "from": "2026-01-01T00:00:00Z",
    "count": 1,
    "include": [
        "chart",
        "houses",
        "aspects"
    ]
}),
});
const data = await response.json();
console.log(data);

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

const api = new AstroApiClient('ak_test_<DEIN_KEY>');
const response = await api.returns({
    "natal": {
        "datetime": "1980-05-17T14:32:00",
        "timezone": "Europe/Berlin",
        "location": {
            "latitude": 52.52,
            "longitude": 13.405
        }
    },
    "planet": [
        "sun",
        "jupiter"
    ],
    "from": "2026-01-01T00:00:00Z",
    "count": 1,
    "include": [
        "chart",
        "houses",
        "aspects"
    ]
});
console.log(response);

import requests

url = 'https://astroapi.services/v1/returns'
headers = {'X-API-Key': 'ak_test_<DEIN_KEY>'}
payload = {
    "natal": {
        "datetime": "1980-05-17T14:32:00",
        "timezone": "Europe/Berlin",
        "location": {
            "latitude": 52.52,
            "longitude": 13.405
        }
    },
    "planet": [
        "sun",
        "jupiter"
    ],
    "from": "2026-01-01T00:00:00Z",
    "count": 1,
    "include": [
        "chart",
        "houses",
        "aspects"
    ]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

from astroapi_client import AstroApiClient

api = AstroApiClient('ak_test_<DEIN_KEY>')
response = api.returns({
    'natal': {
        'datetime': '1980-05-17T14:32:00',
        'timezone': 'Europe/Berlin',
        'location': {
            'latitude': 52.52,
            'longitude': 13.405,
        },
    },
    'planet': [
        'sun',
        'jupiter',
    ],
    'from': '2026-01-01T00:00:00Z',
    'count': 1,
    'include': [
        'chart',
        'houses',
        'aspects',
    ],
})
print(response)