# Astrology API Integration Guide

This document helps you integrate the astrology API into any web app, mobile app, or backend service.

## 1. Overview

The API is available through a single endpoint:

- Base URL: http://localhost/astrology_api/api-local.php
- Replace the base URL with your hosted domain when deploying.

The API accepts JSON requests and returns JSON responses.

## 2. Request Format

Send a POST request with two fields:

```json
{
  "endpoint": "muhurat",
  "payload": {
    "day": 20,
    "month": 10,
    "year": 1978,
    "hour": 5,
    "min": 52,
    "lat": 22.5354262,
    "lon": 88.3633146,
    "tzone": 5.5,
    "purpose": "Marriage"
  }
}
```

### Required fields

- endpoint: the API feature you want to use
- payload: object containing the input data for that feature

## 3. Supported Endpoints

| Endpoint | Method | Description |
|---|---|---|
| muhurat | POST | Get auspicious dates for the next N days |
| muhurat/date | POST | Analyze one specific date |
| muhurat/range | POST | Analyze a custom date range |
| muhurat/purposes | GET or POST | Get all supported purposes/categories |
| panchanga | POST | Get panchanga details like tithi, nakshatra, yoga |
| chart | POST | Get birth chart / planetary positions |
| vimshottari | POST | Get Vimshottari dasha details |
| gochar | POST | Get transit/Gochar information |
| matchmaking | POST | Get compatibility analysis |
| kp | POST | Get KP-style chart details |
| jaimini | POST | Get Jaimini-based chart analysis |
| report | POST | Get a local narrative report |

## 4. Common Payload Fields

Most endpoints use the same birth data structure:

```json
{
  "day": 20,
  "month": 10,
  "year": 1978,
  "hour": 5,
  "min": 52,
  "lat": 22.5354262,
  "lon": 88.3633146,
  "tzone": 5.5
}
```

### Optional fields

- purpose: event purpose, for example "Marriage", "Business", "Education"
- search_days: number of days to scan, from 1 to 60 (default 30)
- house_system: "whole_sign" or "equal"
- target_date: date in YYYY-MM-DD format for specific-date analysis
- start_date / end_date: for range analysis

## 5. Example: Muhurat API

### cURL

```bash
curl -X POST http://localhost/astrology_api/api-local.php \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "muhurat",
    "payload": {
      "day": 20,
      "month": 10,
      "year": 1978,
      "hour": 5,
      "min": 52,
      "lat": 22.5354262,
      "lon": 88.3633146,
      "tzone": 5.5,
      "purpose": "Marriage",
      "search_days": 60
    }
  }'
```

### PHP

```php
<?php
$payload = [
    'endpoint' => 'muhurat',
    'payload' => [
        'day' => 20,
        'month' => 10,
        'year' => 1978,
        'hour' => 5,
        'min' => 52,
        'lat' => 22.5354262,
        'lon' => 88.3633146,
        'tzone' => 5.5,
        'purpose' => 'Marriage',
        'search_days' => 60
    ]
];

$ch = curl_init('http://localhost/astrology_api/api-local.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);
```

### JavaScript / Node.js

```javascript
const response = await fetch('http://localhost/astrology_api/api-local.php', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    endpoint: 'muhurat',
    payload: {
      day: 20,
      month: 10,
      year: 1978,
      hour: 5,
      min: 52,
      lat: 22.5354262,
      lon: 88.3633146,
      tzone: 5.5,
      purpose: 'Marriage',
      search_days: 60
    }
  })
});

const data = await response.json();
console.log(data);
```

## 6. Example Response

A successful muhurat request returns a structure like this:

```json
{
  "status": true,
  "statusCode": 200,
  "data": {
    "birth_details": {
      "date_of_birth": "1978-10-20",
      "time_of_birth": "05:52"
    },
    "purpose": "Marriage",
    "auspicious_dates": [
      {
        "date": "2026-07-30",
        "day_of_week": "Thursday",
        "auspiciousness_score": 82,
        "recommendation": "Highly Auspicious - Excellent day for your purpose",
        "is_auspicious": true
      }
    ],
    "total_found": 5,
    "search_days": 60,
    "calculation_method": "Vedic Astrology Algorithm v1.0"
  },
  "response_time": 82.3,
  "endpoint": "muhurat"
}
```

## 7. Response Notes

### Success response

- status: true
- statusCode: 200
- data: the requested results

### Error response

```json
{
  "status": false,
  "statusCode": 400,
  "error": "Missing endpoint parameter"
}
```

Common error cases:

- 400: invalid JSON or missing required fields
- 404: unknown endpoint
- 500: calculation error

## 8. Using the Other Endpoints

### Panchanga

```json
{
  "endpoint": "panchanga",
  "payload": {
    "day": 28,
    "month": 7,
    "year": 2026,
    "hour": 12,
    "min": 0,
    "lat": 28.6139,
    "lon": 77.2090,
    "tzone": 5.5
  }
}
```

### Birth chart

```json
{
  "endpoint": "chart",
  "payload": {
    "day": 20,
    "month": 10,
    "year": 1978,
    "hour": 5,
    "min": 52,
    "lat": 22.5354262,
    "lon": 88.3633146,
    "tzone": 5.5,
    "house_system": "whole_sign"
  }
}
```

## 9. Integration Tips

- Use HTTPS in production.
- Protect this endpoint with authentication or access control if it is exposed publicly.
- Add rate limiting to avoid abuse.
- Display the returned recommendation and score clearly in your UI.
- For mobile apps, cache results for a short duration to reduce repeated calls.

## 10. Example App Flow

1. Collect birth details from the user.
2. Send them to the API using the appropriate endpoint.
3. Show the returned auspicious dates or chart data in your application.
4. Let users choose a date and display the analysis.

## 11. Local Setup

If you are testing locally:

1. Place the project in XAMPP at: C:\xampp\htdocs\astrology_api
2. Open the API at:
   http://localhost/astrology_api/api-local.php
3. For a GET request, the endpoint returns a list of available endpoints.

## 12. Notes

- The API works locally without any third-party dependency.
- The muhurat calculation uses a built-in Vedic astrology engine.
- The best-suggested-date logic uses a 60-day search window.