General Work
general_workRanks broadly auspicious daily periods such as Abhijit Muhurat, favorable Chaughadia/Gowri periods, and supportive Hora periods, then subtracts Rahu Kaal, Bhadra, and Panchak overlaps.
Aliases accepted: general, generic
Back to Docs
Muhurat Search
Muhurat Search
POST
/api/v2/vedic/muhurat/searchSearch a date range for public Vedic auspicious windows using purpose-specific Muhurat rules, Panchang factors, and avoid-period subtraction.
Authentication: send x-api-key.
Full URL
https://api.freeastroapi.com/api/v2/vedic/muhurat/searchSafe retries with Idempotency-Key
Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Reuse the same key only when retrying the exact same method, path, query string, and JSON body after a timeout or network failure.
A completed replay returns the first response with Idempotency-Replayed: true, does not rerun the calculation, and does not consume extra quota. Keys are retained for about 24 hours.
Reusing a key with a changed request returns 409 idempotency_key_reused. A duplicate while the first request is still running returns 409 request_in_progress with Retry-After.
What It Returns
A ranked list of public auspicious windows for the requested purpose, including start/end times, duration, score, quality, source periods, warnings, purpose criteria, and calculation metadata.
Search Purposes
The public search endpoint normalizes aliases into one of the supported purpose values below. Purpose-specific modes first calculate local Panchang intervals, then intersect favorable tithi and nakshatra periods with any weekday, lunar-month, duration, or Lagna rules for that activity. Rahu Kaal, Bhadra, and Panchak are not hidden; overlaps are returned in the criteria and warnings so clients can explain why a window may need caution.
Vehicle Purchase
vehicle_purchaseRequires favorable tithi, nakshatra, and weekday intersections, excludes Adhik Maas, rejects short fragments below the calibrated duration threshold, and requires overlap with sampled auspicious Lagna signs for vehicle acquisition.
Aliases accepted: vehicle, car, car_purchase
Property Purchase
property_purchaseUses property-specific favorable tithi and nakshatra intersections for stability and acquisition, excludes Adhik Maas, and keeps Rahu Kaal, Bhadra, and Panchak overlaps visible as warnings.
Aliases accepted: property, land_purchase
Griha Pravesh
griha_praveshRequires favorable tithi, nakshatra, weekday, and lunar month combinations for house entry, excludes Adhik Maas, and marks avoid-period overlaps so the full public window remains auditable.
Aliases accepted: griha_pravesha, housewarming, home_entry
Namkaran
namkaranUses naming-ceremony tithi, nakshatra, and weekday rules, excludes Adhik Maas, and returns the qualifying public windows with Panchang criteria and avoid-period warnings.
Aliases accepted: naming, naming_ceremony
Mundan
mundanCombines Mundan-specific favorable tithis, nakshatras, weekdays, and lunar months, excludes Adhik Maas, and exposes avoid-period overlaps for astrologer review.
Aliases accepted: mundan_ceremony, first_haircut
Personalized birth-chart checks are intentionally separate. Use Personalized Muhurat Search when you need natal Tara Bala, Chandra Bala, event Lagna scoring, strict best-moment selection, rejected-window reasons, or child-specific samskara context.
Example Request
curl -X POST "https://api.freeastroapi.com/api/v2/vedic/muhurat/search" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"purpose": "vehicle_purchase",
"start_date": "2026-04-01",
"end_date": "2026-04-30",
"city": "New Delhi",
"lat": 28.62137,
"lng": 77.2148,
"ayanamsha": "lahiri",
"language": "en",
"limit": 3
}'Request Parameters
Provide either city or both lat and lng. Coordinates are recommended for stable production results.
Field
purpose
Type
string
Required
No
Description
Search purpose. Supported values: general_work, vehicle_purchase, property_purchase, griha_pravesh, namkaran, and mundan.
Field
start_date
Type
string
Required
Yes
Description
Inclusive local start date as YYYY-MM-DD.
Field
end_date
Type
string
Required
Yes
Description
Inclusive local end date as YYYY-MM-DD. Maximum 31 days.
Field
city
Type
string
Required
No
Description
Location name. Optional when lat/lng are provided.
Field
lat
Type
float
Required
No
Description
Latitude. Recommended for stable production results.
Field
lng
Type
float
Required
No
Description
Longitude. Recommended for stable production results.
Field
tz_str
Type
string
Required
No
Description
Optional timezone override such as Asia/Kolkata, Europe/London, AUTO, or LMT. Defaults to AUTO when omitted.
Field
ayanamsha
Type
string
Required
No
Description
Vedic ayanamsha. Default is lahiri.
Field
language
Type
string
Required
No
Description
Response language. Only en is currently supported.
Field
limit
Type
integer
Required
No
Description
Maximum number of best windows to return. Allowed range: 1-50. Default is 10.
Response Shape
Field
purpose
Type
string
Required
n/a
Description
Normalized search purpose.
Field
range
Type
object
Required
n/a
Description
Start date, end date, and day count searched.
Field
best_windows
Type
array
Required
n/a
Description
Ranked public auspicious windows for the requested purpose.
Field
best_windows[].score
Type
integer
Required
n/a
Description
Public ranking score for the window.
Field
best_windows[].quality
Type
string
Required
n/a
Description
Window quality label, such as auspicious.
Field
best_windows[].criteria
Type
object
Required
n/a
Description
Purpose rules, Panchang factors, avoid-period overlaps, and source periods used for the window.
Field
best_moment
Type
object
Required
n/a
Description
Present only when a strict personalized layer selects an exact moment; null for generic public search.
Field
metadata
Type
object
Required
n/a
Description
Endpoint version, ruleset, ayanamsha, timezone, calculation basis, and search notes.
Real Request Example
This request searches public Vehicle Purchase Muhurat windows for New Delhi in April 2026.
{
"purpose": "vehicle_purchase",
"start_date": "2026-04-01",
"end_date": "2026-04-30",
"city": "New Delhi",
"lat": 28.62137,
"lng": 77.2148,
"ayanamsha": "lahiri",
"language": "en",
"limit": 3
}Real Response Example
This response was generated from the current V2 endpoint implementation for the example payload.
V2
{
"acceptable_moments": [],
"avoid_moments": [],
"best_moment": null,
"best_windows": [
{
"best_moment": null,
"criteria": {
"avoid_periods": [
{
"end": "2026-04-01T19:23:43.161303+05:30",
"name": "Bhadra",
"start": "2026-04-01T07:09:16.417423+05:30",
"status": "warning_overlap"
}
],
"duration": {
"minimum_minutes": 240,
"status": "meets_minimum",
"value_minutes": 832.78
},
"lagna": {
"allowed_signs": [
{
"name": "Gemini",
"sign_id": 3
},
{
"name": "Cancer",
"sign_id": 4
},
{
"name": "Leo",
"sign_id": 5
},
{
"name": "Virgo",
"sign_id": 6
},
{
"name": "Scorpio",
"sign_id": 8
},
{
"name": "Sagittarius",
"sign_id": 9
},
{
"name": "Pisces",
"sign_id": 12
}
],
"matched_signs": [
{
"name": "Leo",
"sample_time": "2026-04-01T16:18:08.351510+05:30",
"sign_id": 5
},
{
"name": "Virgo",
"sample_time": "2026-04-01T18:00:00+05:30",
"sign_id": 6
},
{
"name": "Scorpio",
"sample_time": "2026-04-01T22:00:00+05:30",
"sign_id": 8
},
{
"name": "Sagittarius",
"sample_time": "2026-04-02T01:00:00+05:30",
"sign_id": 9
},
{
"name": "Pisces",
"sample_time": "2026-04-02T06:00:00+05:30",
"sign_id": 12
}
],
"status": "overlaps_favorable_lagna"
},
"lunar_month": {
"status": "not_restricted",
"value": "Chaitra"
},
"nakshatra": {
"status": "favorable",
"value": "Hasta"
},
"publication_window": {
"max_start_hour": 25,
"status": "within_calibrated_start_range"
},
"purpose": {
"label": "Vehicle Purchase Muhurat",
"status": "selected",
"value": "vehicle_purchase"
},
"tithi": {
"status": "favorable",
"value": "Poornima"
},
"weekday": {
"status": "favorable",
"value": "Wednesday"
}
},
"date": "2026-04-01",
"duration_minutes": 832.78,
"end": "2026-04-02T06:10:55.359326+05:30",
"end_time": "30:10:55",
"personal_score": null,
"public_score": null,
"quality": "auspicious",
"reasons": [
"Vehicle Purchase Muhurat",
"Poornima Tithi",
"Hasta Nakshatra",
"Chaitra lunar month",
"Auspicious Lagna"
],
"score": 94,
"source_periods": [
"Vehicle Purchase Muhurat",
"Poornima Tithi",
"Hasta Nakshatra",
"Auspicious Lagna"
],
"start": "2026-04-01T16:18:08.351510+05:30",
"start_time": "16:18:08",
"warnings": [
"Overlaps Bhadra."
]
},
{
"best_moment": null,
"criteria": {
"avoid_periods": [
{
"end": "2026-04-02T15:32:21.417644+05:30",
"name": "Rahu Kaal",
"start": "2026-04-02T13:58:39.574591+05:30",
"status": "warning_overlap"
}
],
"duration": {
"minimum_minutes": 240,
"status": "meets_minimum",
"value_minutes": 1439.17
},
"lagna": {
"allowed_signs": [
{
"name": "Gemini",
"sign_id": 3
},
{
"name": "Cancer",
"sign_id": 4
},
{
"name": "Leo",
"sign_id": 5
},
{
"name": "Virgo",
"sign_id": 6
},
{
"name": "Scorpio",
"sign_id": 8
},
{
"name": "Sagittarius",
"sign_id": 9
},
{
"name": "Pisces",
"sign_id": 12
}
],
"matched_signs": [
{
"name": "Pisces",
"sample_time": "2026-04-02T06:10:36.359326+05:30",
"sign_id": 12
},
{
"name": "Gemini",
"sample_time": "2026-04-02T11:00:00+05:30",
"sign_id": 3
},
{
"name": "Cancer",
"sample_time": "2026-04-02T13:00:00+05:30",
"sign_id": 4
},
{
"name": "Leo",
"sample_time": "2026-04-02T15:00:00+05:30",
"sign_id": 5
},
{
"name": "Virgo",
"sample_time": "2026-04-02T18:00:00+05:30",
"sign_id": 6
},
{
"name": "Scorpio",
"sample_time": "2026-04-02T22:00:00+05:30",
"sign_id": 8
},
{
"name": "Sagittarius",
"sample_time": "2026-04-03T01:00:00+05:30",
"sign_id": 9
}
],
"status": "overlaps_favorable_lagna"
},
"lunar_month": {
"status": "not_restricted",
"value": "Chaitra"
},
"nakshatra": {
"status": "favorable",
"value": "Hasta / Chitra"
},
"publication_window": {
"max_start_hour": 25,
"status": "within_calibrated_start_range"
},
"purpose": {
"label": "Vehicle Purchase Muhurat",
"status": "selected",
"value": "vehicle_purchase"
},
"tithi": {
"status": "favorable",
"value": "Poornima / Pratipada"
},
"weekday": {
"status": "favorable",
"value": "Thursday"
}
},
"date": "2026-04-02",
"duration_minutes": 1439.17,
"end": "2026-04-03T06:09:46.767503+05:30",
"end_time": "30:09:46",
"personal_score": null,
"public_score": null,
"quality": "auspicious",
"reasons": [
"Vehicle Purchase Muhurat",
"Poornima / Pratipada Tithi",
"Hasta / Chitra Nakshatra",
"Chaitra lunar month",
"Auspicious Lagna"
],
"score": 94,
"source_periods": [
"Vehicle Purchase Muhurat",
"Poornima / Pratipada Tithi",
"Hasta / Chitra Nakshatra",
"Auspicious Lagna"
],
"start": "2026-04-02T06:10:36.359326+05:30",
"start_time": "06:10:36",
"warnings": [
"Overlaps Rahu Kaal."
]
},
{
"best_moment": null,
"criteria": {
"avoid_periods": [],
"duration": {
"minimum_minutes": 240,
"status": "meets_minimum",
"value_minutes": 766.08
},
"lagna": {
"allowed_signs": [
{
"name": "Gemini",
"sign_id": 3
},
{
"name": "Cancer",
"sign_id": 4
},
{
"name": "Leo",
"sign_id": 5
},
{
"name": "Virgo",
"sign_id": 6
},
{
"name": "Scorpio",
"sign_id": 8
},
{
"name": "Sagittarius",
"sign_id": 9
},
{
"name": "Pisces",
"sign_id": 12
}
],
"matched_signs": [
{
"name": "Cancer",
"sample_time": "2026-04-06T14:11:31.352926+05:30",
"sign_id": 4
},
{
"name": "Leo",
"sample_time": "2026-04-06T15:00:00+05:30",
"sign_id": 5
},
{
"name": "Virgo",
"sample_time": "2026-04-06T17:00:00+05:30",
"sign_id": 6
},
{
"name": "Scorpio",
"sample_time": "2026-04-06T22:00:00+05:30",
"sign_id": 8
},
{
"name": "Sagittarius",
"sample_time": "2026-04-07T00:00:00+05:30",
"sign_id": 9
}
],
"status": "overlaps_favorable_lagna"
},
"lunar_month": {
"status": "not_restricted",
"value": "Chaitra"
},
"nakshatra": {
"status": "favorable",
"value": "Anuradha"
},
"publication_window": {
"max_start_hour": 25,
"status": "within_calibrated_start_range"
},
"purpose": {
"label": "Vehicle Purchase Muhurat",
"status": "selected",
"value": "vehicle_purchase"
},
"tithi": {
"status": "favorable",
"value": "Panchami"
},
"weekday": {
"status": "favorable",
"value": "Monday"
}
},
"date": "2026-04-06",
"duration_minutes": 766.08,
"end": "2026-04-07T02:57:35.995205+05:30",
"end_time": "26:57:35",
"personal_score": null,
"public_score": null,
"quality": "auspicious",
"reasons": [
"Vehicle Purchase Muhurat",
"Panchami Tithi",
"Anuradha Nakshatra",
"Chaitra lunar month",
"Auspicious Lagna"
],
"score": 94,
"source_periods": [
"Vehicle Purchase Muhurat",
"Panchami Tithi",
"Anuradha Nakshatra",
"Auspicious Lagna"
],
"start": "2026-04-06T14:11:31.352926+05:30",
"start_time": "14:11:31",
"warnings": []
}
],
"metadata": {
"ayanamsha": "lahiri",
"calculation_basis": "purpose_specific_tithi_nakshatra_intersections_with_avoid_period_warnings",
"calculation_notes": [
"Purpose-specific searches use calibrated tithi and nakshatra intersections for the requested activity.",
"Vehicle Purchase also requires overlap with an auspicious Lagna sample.",
"Adhik Maas is excluded for these ceremony searches.",
"Rahu Kaal, Bhadra, and Panchak overlaps are returned as warnings to preserve AstroSage-style full windows.",
"Vehicle Purchase omits short fragments below the calibrated publication-duration threshold."
],
"endpoint_version": "v2",
"personalization_basis": null,
"public_candidate_count": null,
"ruleset_version": "freeastro_muhurat_search_v2",
"sampling_interval_minutes": null,
"scan_months_requested": null,
"scanned_months": null,
"scanned_ranges": null,
"search_mode": null,
"strict_rejection_policy": null,
"strict_selection_status": null,
"strictness": null,
"subject": null,
"timezone_used": "Asia/Kolkata"
},
"no_compromise_moment": null,
"purpose": "vehicle_purchase",
"range": {
"day_count": 30,
"end_date": "2026-04-30",
"start_date": "2026-04-01"
},
"rejected_windows": [],
"selection_explanation": null
}FAQ
Is this a public Muhurat search or a personalized election?
This endpoint is public and location/date based. It ranks purpose-specific auspicious windows from Panchang factors and avoid periods, but it does not use the person's birth chart. Use personalized Muhurat search when natal Tara Bala, Chandra Bala, and event-chart selection are required.
Why can a purpose return no windows?
Some purposes have strict public filters, and a short date range may not contain matching tithi, nakshatra, weekday, and avoid-period conditions. A 200 response with an empty best_windows array means the API completed the search and found no suitable public windows.
How large can a search range be?
The public endpoint is capped at 31 days per request. For longer planning workflows, call it month by month and keep the same location inputs so scoring remains comparable.
How should astrologers read score and quality?
Score is a practical ranking signal for API consumers, not a standalone astrological verdict. The criteria object shows the supporting Panchang factors, source periods, warnings, and avoid-period context that explain why each window was included.