=== Occult API — Panchang, Kundli & Horoscope ===
Contributors: occultapi
Tags: panchang, astrology, horoscope, kundli, vedic
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add Panchang, muhurat timings, vrat and festival dates, a birth chart form and horoscope blocks to your site, from real astronomical data.

== Description ==

Fourteen blocks, backed by the Occult API — drag any of them into the block editor, no shortcode syntax required (each also has a plain shortcode, for a Classic Editor or a template file):

**Panchang & timings**

* Panchang — the five angas for today: tithi, nakshatra, yoga, karana and vaara.
* Rahu Kaal — plus Yamaganda and Gulika Kaal, the day's three inauspicious windows.
* Choghadiya — the eight-fold day/night division, with the current period marked.
* Abhijit Muhurat and Brahma Muhurat — the two auspicious windows people search for by name.
* Durmuhurat — the day's one or two short unfavourable windows.

**Vrat & festival dates**

* Ekadashi, Amavasya, Purnima, Pradosh and Sankashti Chaturthi Dates — upcoming dates for a year, nearest first.
* Festival Calendar — upcoming dates from the Hindu, Jain, Sikh, Christian or Ekadashi calendar.

**Chart & horoscope**

* Rashifal — a horoscope for one sign, daily through yearly.
* Kundli Form — a birth chart form your visitors fill in, returning planets by sign and nakshatra.

Every block ships with a real default look (a card, your site's own colours available underneath) and a one-click Minimal style for themes that already supply their own section styling — no colour picker required unless you want one.

Positions come from the Swiss Ephemeris, not from a lookup table, so they agree with a real ephemeris rather than approximating one.

**You need a free Occult API key.** The plugin does nothing until you add one in Settings → Occult API.

= What this costs you =

Calculations are billed to your own Occult API account, one credit per calculation. The plugin caches aggressively so you are not billed repeatedly for the same answer:

* Panchang, Rahu Kaal, Choghadiya, Abhijit/Brahma Muhurat, Durmuhurat — one call per day per location, then cached for six hours.
* Horoscope — one call per sign per period, then cached for six hours.
* Kundli — one call per distinct set of birth details, cached for a week. Identical details cost nothing the second time.
* Ekadashi, Amavasya, Purnima, Pradosh, Sankashti Chaturthi Dates — one call per year (all five read the same cached response), cached for thirty days.
* Festival Calendar — one call per year per calendar, cached for thirty days.

The Kundli form is the only thing a visitor can spend a credit with, so it is rate limited per IP address — ten per hour by default, adjustable with the `occult_api_kundli_hourly_limit` filter.

= Hindi =

When your site runs in Hindi, the Panchang shows Hindi names for the angas. These come from the API itself rather than from a transliteration table in the plugin.

== External services ==

This plugin connects to the Occult API (https://occultapi.com), a third-party service, to perform astrological calculations. Nothing is sent until you save an API key.

**What is sent, and when:**

* When a page containing the Panchang, Rahu Kaal, Choghadiya, Abhijit Muhurat, Brahma Muhurat or Durmuhurat block is rendered: the date, latitude, longitude and UTC offset you configured.
* When a page containing the Ekadashi, Amavasya, Purnima, Pradosh or Sankashti Chaturthi Dates block is rendered: the year, and the latitude, longitude and UTC offset you configured.
* When a page containing the Festival Calendar block is rendered: the year and the calendar category selected. No location is sent - this block does not use one.
* When a page containing the Rashifal block is rendered: the zodiac sign and period selected.
* When a visitor submits the Kundli form: the date and time of birth they entered, and the latitude, longitude and UTC offset you configured.
* When you press "Verify key" on the settings page: nothing but the key itself.

Every request also carries your API key and your site's URL, the latter so the service can identify plugin traffic in its own logs.

**What is never sent:** visitor IP addresses, names, email addresses, page URLs, or any analytics. The plugin does not track visitors.

The API key is stored on your server and used only in server-side requests. It is never printed into a page, so it is not exposed to visitors.

* Terms of service: https://occultapi.com/terms
* Privacy policy: https://occultapi.com/privacy

== Installation ==

1. Install and activate the plugin.
2. Get a free API key at https://occultapi.com/signup.
3. Go to Settings → Occult API, paste the key, and set your default latitude, longitude and UTC offset.
4. Press "Verify key" to confirm it works. This costs no credits.
5. Add a shortcode to any post, page or widget.

== Frequently Asked Questions ==

= Do I need an API key? =

Yes. The plugin has no built-in key and does nothing without one. Sign up free at https://occultapi.com/signup.

= Will this run up a bill? =

Every result is cached, so a page with a Panchang widget costs one credit a day regardless of how many people visit it. The one thing visitors can spend credits on is the Kundli form, which is rate limited per IP address.

= Why is my Panchang wrong by a day? =

Almost always the UTC offset or longitude in Settings. A tithi begins and ends at a precise moment, so a chart calculated for the wrong place or offset can land either side of a boundary. Check that the offset matches the location you entered, not the server's own timezone.

= Can I show sunrise and sunset? =

Not in this version. The endpoint behind the widget returns the five angas and nothing solar. Sunrise and sunset are a separate calculation and are planned for a later release.

= Does it work with page caching? =

Yes, and it helps. The plugin caches API responses itself, so a page cache on top simply serves the already-cached result.

== Screenshots ==

1. The Panchang block, the default Card style.
2. The Rahu Kaal block, showing Rahu Kaal, Yamaganda and Gulika Kaal together.
3. The Rashifal block, a full daily reading across every aspect.
4. Settings → Occult API, with key verification.

== Changelog ==

= 0.1.0 =
* First release: fourteen blocks (Panchang, Rahu Kaal, Choghadiya, Abhijit Muhurat, Brahma Muhurat, Durmuhurat, Ekadashi/Amavasya/Purnima/Pradosh/Sankashti Chaturthi Dates, Festival Calendar, Rashifal, Kundli), each a native block editor block with a matching shortcode.
* A default Card look for every block, and a one-click Minimal style for themes that supply their own section styling.
* Server-side API calls only; the key is never exposed to the browser.
* Response caching per tool, and per-IP rate limiting on the Kundli form.
* Hindi names on the Panchang when the site locale is Hindi.

== Upgrade Notice ==

= 0.1.0 =
First release.
