Planet Returns List

The Planet Returns List API provides a list of exact planetary return dates for a given planet within a specified year. Planetary returns mark the moments when a planet returns to the same position it occupied at birth, symbolizing cycles of renewal, reflection, and development in astrology.

Supported Language Codes

Support Article URL - https://support.divineapi.com/general-api-support/translating-a-natal-apis-into-a-different-language

Code	Language
en	English
hi	Hindi
pt	Portuguese
fr	French
de	German
ja	Japanese
tr	Turkish
ru	Russian
it	Italian
es	Spanish
nl	Dutch
pl	Polish

Guide: These languages are supported by this API. You can use by passing "lan" in the body with a value of the desired language.

House System Codes

Support Article URL - https://support.divineapi.com/western-astrology-apis/how-to-change-the-house-system-code-in-natal-astrology

Code	Description
P	Placidus
K	Koch
R	Regiomontanus
C	Campanus
A	Equal
W	Equal, whole sign
N	Whole sign, Aries = 1st house
X	Axial rotation system / Meridian houses
T	Polich/Page (topocentric)
M	Morinus
O	Porphyry
B	Alcabitius
D	Equal / MC
E	Equal = A
F	Carter poli-equatorial
G	36 Gauquelin sectors
H	Horizon / azimuth
I	Sunshine
i	Sunshine alternative
L	Pullen
Q	Pullen S-ratio
S	Sripati
U	Krusinski-Pisa-Goelzer
V	Equal Vehlow
Y	APC houses

Note: The default house system used is P - Placidus.

Allowed Planets

SUN
MOON
MERCURY
VENUS
MARS
JUPITER
SATURN
URANUS
NEPTUNE

Endpoint

POST https://astroapi-8.divineapi.com/western-api/v1/planet-returns-list

Returns Planet Returns List in response.

Headers

Name	Type	Description
Authorization*	String	Your API Access Tokeneg: Bearer {token}

Request Body

Name	Type	Description
api_key*	String	Your API key
planet*	String	Planet, e.g., MOON
full_name*	String	Full name, e.g., Rahul Kumar
day*	Integer	Date of birth, e.g., 24
month*	Integer	Month of birth, e.g., 05
year*	Integer	Year of birth, e.g., 2023
hour*	Integer	Hour, e.g., 14
min*	Integer	Minute, e.g., 40
sec*	Integer	Second, e.g., 43
gender*	String	Gender, e.g., male
place*	String	Birth place, e.g., New Delhi
lat*	Float	Latitude, e.g., 28.7041
lon*	Float	Longitude, e.g., 77.1025
tzone*	Float	Timezone, e.g., 5.5 Timezone List
lan	String	Language en/hi, default en
return_year*	Integer	Return year, e.g., 2024
return_lat*	Float	Return latitude, e.g., 19.0760
return_lon*	Float	Return longitude, e.g., 72.8774
return_tzone*	Float	Return timezone, e.g., 5.5
return_place*	String	Return place, e.g., Mumbai, Maharashtra, India
house_system	String	House system code, default - P (Placidus)

200: OK Planet Returns List fetched successfully

{
    "status": "success",
    "code": 200,
    "message": "Request successful",
    "data": {
        "planet_return": [
            {
                "return_datetime": "2027-01-01 05:17:00",
                "return_key": "MOON_P_1798780620000"
            },
            {
                "return_datetime": "2027-01-28 12:38:00",
                "return_key": "MOON_P_1801139880000"
            },
            {
                "return_datetime": "2027-02-24 21:58:00",
                "return_key": "MOON_P_1803506280000"
            },
            {
                "return_datetime": "2027-03-24 08:01:00",
                "return_key": "MOON_P_1805875260000"
            },
            {
                "return_datetime": "2027-04-20 16:59:00",
                "return_key": "MOON_P_1808240340000"
            },
            {
                "return_datetime": "2027-05-18 00:01:00",
                "return_key": "MOON_P_1810598460000"
            },
            {
                "return_datetime": "2027-06-14 05:39:00",
                "return_key": "MOON_P_1812951540000"
            },
            {
                "return_datetime": "2027-07-11 11:21:00",
                "return_key": "MOON_P_1815304860000"
            },
            {
                "return_datetime": "2027-08-07 18:34:00",
                "return_key": "MOON_P_1817663640000"
            },
            {
                "return_datetime": "2027-09-04 03:42:00",
                "return_key": "MOON_P_1820029320000"
            },
            {
                "return_datetime": "2027-10-01 13:52:00",
                "return_key": "MOON_P_1822398720000"
            },
            {
                "return_datetime": "2027-10-28 23:25:00",
                "return_key": "MOON_P_1824765900000"
            },
            {
                "return_datetime": "2027-11-25 06:59:00",
                "return_key": "MOON_P_1827125940000"
            },
            {
                "return_datetime": "2027-12-22 12:41:00",
                "return_key": "MOON_P_1829479260000"
            }
        ],
        "planet_data": {
            "name": "Moon",
            "sign": "li",
            "speed": "11.9818279",
            "is_retro": "false",
            "longitude": "24:29:55",
            "full_degree": "204.4984819"
        }
    }
}

Example Code Implementations

Below are example implementations in various programming environments.

cURL

curl --location 'https://astroapi-8.divineapi.com/western-api/v1/planet-returns-list' \
--header 'Authorization: Bearer your API Access Token' \
--form 'api_key="your API Key"' \
--form 'planet="Moon"' \
--form 'full_name="Rahul Kumar"' \
--form 'day="24"' \
--form 'month="5"' \
--form 'year="2023"' \
--form 'hour="14"' \
--form 'min="40"' \
--form 'sec="43"' \
--form 'gender="male"' \
--form 'place="New Delhi"' \
--form 'lat="28.7041"' \
--form 'lon="77.1025"' \
--form 'tzone="5.5"' \
--form 'lan="en"' \
--form 'return_year="2024"' \
--form 'return_lat="19.0760"' \
--form 'return_lon="72.8774"' \
--form 'return_tzone="5.5"' \
--form 'return_place="Mumbai, Maharashtra, India"' \
--form 'house_system="P"'

NodeJS

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://astroapi-8.divineapi.com/western-api/v1/planet-returns-list',
  'headers': {
    'Authorization': 'Bearer your API Access Token'
  },
  formData: {
    'api_key': 'your API Key',
    'planet': 'Moon',
    'full_name': 'Rahul Kumar',
    'day': '24',
    'month': '5',
    'year': '2023',
    'hour': '14',
    'min': '40',
    'sec': '43',
    'gender': 'male',
    'place': 'New Delhi',
    'lat': '28.7041',
    'lon': '77.1025',
    'tzone': '5.5',
    'lan': 'en',
    'return_year': '2024',
    'return_lat': '19.0760',
    'return_lon': '72.8774',
    'return_tzone': '5.5',
    'return_place': 'Mumbai, Maharashtra, India',
    'house_system': 'P'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

JavaScript jQuery AJAX

var form = new FormData();
form.append("api_key", "your API Key");
form.append("planet", "Moon");
form.append("full_name", "Rahul Kumar");
form.append("day", "24");
form.append("month", "5");
form.append("year", "2023");
form.append("hour", "14");
form.append("min", "40");
form.append("sec", "43");
form.append("gender", "male");
form.append("place", "New Delhi");
form.append("lat", "28.7041");
form.append("lon", "77.1025");
form.append("tzone", "5.5");
form.append("lan", "en");
form.append("return_year", "2024");
form.append("return_lat", "19.0760");
form.append("return_lon", "72.8774");
form.append("return_tzone", "5.5");
form.append("return_place", "Mumbai, Maharashtra, India");
form.append("house_system", "P");

var settings = {
  "url": "https://astroapi-8.divineapi.com/western-api/v1/planet-returns-list",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Authorization": "Bearer your API Access Token"
  },
  "processData": false,
  "mimeType": "multipart/form-data",
  "contentType": false,
  "data": form
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

Python

import requests

url = "https://astroapi-8.divineapi.com/western-api/v1/planet-returns-list"

payload = {'api_key': 'your API Key',
'planet': 'Moon',
'full_name': 'Rahul Kumar',
'day': '24',
'month': '5',
'year': '2023',
'hour': '14',
'min': '40',
'sec': '43',
'gender': 'male',
'place': 'New Delhi',
'lat': '28.7041',
'lon': '77.1025',
'tzone': '5.5',
'lan': 'en',
'return_year': '2024',
'return_lat': '19.0760',
'return_lon': '72.8774',
'return_tzone': '5.5',
'return_place': 'Mumbai, Maharashtra, India',
'house_system': 'P'}
files=[

]
headers = {
  'Authorization': 'Bearer your API Access Token'
}

response = requests.request("POST", url, headers=headers, data=payload, files=files)

print(response.text)

Implementation Notes

Use Authorization: Bearer {Your Auth Token} and {Your API Key} securely; never expose them in client-side code.

Provide date, time, and coordinates in correct numeric formats; use decimal timezone values (e.g., 5.5).

Check HTTP status codes, log responses, and handle 4xx/5xx errors gracefully.

Defaults are lan=en and house_system=P; test via Postman first and always use HTTPS for secure communication.