Wedding Electional API Docs | Free Astrology API

Wedding

Beta

POST/api/v2/western/electional/wedding/search

Search comparative wedding election windows with a dual verdict model. The endpoint returns a public recommendation status plus a strict traditional verdict, detailed factor lists, and optional bounded natal resonance for one or two partners.

Full URL

https://api.freeastroapi.com/api/v2/western/electional/wedding/search

Plan and Access

Entry and High plan only. The same tool is exposed through Hosted MCP for Entry and High users.

Hosted MCP tool name: v2_western_electional_wedding_search

The response always keeps doctrinal output separate from comparative ranking via strict_traditional_verdict and status.

Request Body Parameters

Parameter	Type	Req	Description
`search_window`	object	Yes	Search range block. Use local datetimes in the chosen location timezone.
`search_window.start`	string	Yes	Local start datetime or date string for the search window.
`search_window.end`	string	Yes	Local end datetime or date string for the search window.
`search_window.step_minutes`	integer	No	Candidate sampling interval. Defaults to 30. Allowed range: 5 to 240 minutes.
`city`	string	Conditional	Preferred natal-style location syntax. City label for lookup and docs readability. Required when coordinates are omitted.
`lat`	number	Conditional	Preferred natal-style location syntax. Latitude in decimal degrees. Required when `city` is omitted.
`lng`	number	Conditional	Preferred natal-style location syntax. Longitude in decimal degrees. Required when `city` is omitted.
`tz_str`	string	No	Preferred natal-style location syntax. IANA timezone like `Europe/Paris` or `AUTO`. Defaults to `AUTO`.
`location`	object	Legacy	Backward-compatible legacy wrapper. If you already send `location.city`, `location.lat`, `location.lng`, and `location.tz_str`, it still works.
`search_tuning`	object	No	Optional coarse-to-fine search controls for yearly scans.
`search_tuning.mode`	string	No	Use `direct` for a normal scan or `year` for coarse-to-fine yearly search. Defaults to `direct`.
`search_tuning.coarse_step_minutes`	integer	No	Year-mode coarse scan interval. Allowed range: 360 to 1440 minutes.
`max_results`	integer	No	Maximum number of returned windows. Defaults to 5. Allowed range: 1 to 10.
`partner_a`	object	No	Partner A natal block used only for bounded resonance and tie-breaking. Alias `partner_a_natal` is also accepted.
`partner_a.name`	string	No	Display name. Defaults to "Partner".
`partner_a.year`	integer	Yes	Birth year.
`partner_a.month`	integer	Yes	Birth month.
`partner_a.day`	integer	Yes	Birth day.
`partner_a.hour`	integer	No	Birth hour. Defaults to 12.
`partner_a.minute`	integer	No	Birth minute. Defaults to 0.
`partner_a.time_known`	boolean	No	Defaults to true. When false, natal resonance is omitted for that subject.
`partner_a.city`	string	Conditional	Birth city. Required when natal coordinates are omitted.
`partner_a.lat`	number	Conditional	Birth latitude. Required when natal city is omitted.
`partner_a.lng`	number	Conditional	Birth longitude. Required when natal city is omitted.
`partner_a.tz_str`	string	No	IANA timezone for the natal chart. Defaults to `AUTO`.
`partner_b`	object	No	Partner B natal block used only for bounded resonance and tie-breaking. Alias `partner_b_natal` is also accepted.
`partner_b.name`	string	No	Display name. Defaults to "Partner".
`partner_b.year`	integer	Yes	Birth year.
`partner_b.month`	integer	Yes	Birth month.
`partner_b.day`	integer	Yes	Birth day.
`partner_b.hour`	integer	No	Birth hour. Defaults to 12.
`partner_b.minute`	integer	No	Birth minute. Defaults to 0.
`partner_b.time_known`	boolean	No	Defaults to true. When false, natal resonance is omitted for that subject.
`partner_b.city`	string	Conditional	Birth city. Required when natal coordinates are omitted.
`partner_b.lat`	number	Conditional	Birth latitude. Required when natal city is omitted.
`partner_b.lng`	number	Conditional	Birth longitude. Required when natal city is omitted.
`partner_b.tz_str`	string	No	IANA timezone for the natal chart. Defaults to `AUTO`.

Sample Code

This is the real live production request used on April 22, 2026, with the API key redacted. The preferred location syntax now matches the natal endpoint with top-level city, lat, lng, and tz_str. Optional natal blocks are omitted in the example but documented above.

curl -X POST "https://api.freeastroapi.com/api/v2/western/electional/wedding/search" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
  "search_window": {
    "start": "2026-06-01T09:00:00",
    "end": "2026-06-01T18:00:00",
    "step_minutes": 60
  },
  "city": "Paris",
  "lat": 48.8566,
  "lng": 2.3522,
  "tz_str": "Europe/Paris",
  "max_results": 1
}'

Real Response Example

This is a trimmed real production response captured on April 22, 2026 for the request shown above. Repeated factor arrays are shortened for readability, but every field shown comes from the live API.

{
  "meta": {
    "endpoint": "/api/v2/western/electional/wedding/search",
    "scoring_version": "clean_room_wedding_v2",
    "calibration_version": "public_calibration_v1",
    "search_mode": "direct",
    "window_strategy": "direct",
    "ranking_basis": "Comparative ranking is relative to the scanned search window after year-mode refinement when used.",
    "resolved_timezone": "Europe/Paris",
    "scanned_candidates": 10,
    "coarse_candidates_scanned": 10,
    "refined_candidates_scanned": 0,
    "returned_candidates": 1,
    "advisories": [],
    "search_start_local": "2026-06-01T09:00:00+02:00",
    "search_end_local": "2026-06-01T18:00:00+02:00",
    "step_minutes": 60
  },
  "results": [
    {
      "rank": 1,
      "event_time_local": "2026-06-01T15:00:00+02:00",
      "event_time_utc": "2026-06-01T13:00:00Z",
      "score_total": 9,
      "confidence_level": "low",
      "quality_band": "poor",
      "status": "reject",
      "strict_traditional_verdict": "blemished",
      "strict_traditional_severity": "major",
      "comparative_window_rank": 1,
      "comparative_window_percentile": 100,
      "best_available_in_window": true,
      "review_flags": [
        "moon_void_of_course_stop",
        "moon_waning_strict",
        "saturn_pressures_venus_strict"
      ],
      "hard_stops": [
        {
          "code": "moon_void_of_course_stop",
          "title": "Moon void of course",
          "score": 0,
          "detail": "Moon void of course",
          "severity": "major"
        },
        {
          "code": "moon_waning_strict",
          "title": "Waning Moon",
          "score": 0,
          "detail": "Waning Moon",
          "severity": "caution"
        },
        {
          "code": "saturn_pressures_venus_strict",
          "title": "Saturn pressures Venus",
          "score": 0,
          "detail": "Saturn pressures Venus, orb 3.75",
          "severity": "caution"
        }
      ],
      "supporting_factors": [
        {
          "code": "moon_unafflicted",
          "title": "Moon free from hard malefic pressure",
          "score": 6,
          "detail": "Moon free from hard malefic pressure"
        },
        {
          "code": "venus_direct",
          "title": "Venus direct",
          "score": 5,
          "detail": "Venus direct"
        },
        {
          "code": "venus_helpful_house",
          "title": "Venus in a wedding-supportive house",
          "score": 5,
          "detail": "Venus in a wedding-supportive house"
        },
        {
          "code": "h7_ruler_dignified",
          "title": "7th ruler dignified",
          "score": 4,
          "detail": "7th ruler dignified"
        }
      ],
      "caution_factors": [
        {
          "code": "venus_malefic_pressure",
          "title": "Venus under hard malefic pressure",
          "score": -8,
          "detail": "Venus under hard malefic pressure"
        },
        {
          "code": "moon_waning",
          "title": "Waning Moon",
          "score": -4,
          "detail": "Waning Moon"
        }
      ],
      "natal_resonance": null
    }
  ]
}

Response Fields

Field	Meaning
`meta.endpoint`	Resolved API route that produced the payload.
`meta.scoring_version / meta.calibration_version`	Version tags for the deployed scoring contract and its calibration set.
`meta.search_mode / meta.window_strategy / meta.ranking_basis`	Search strategy metadata. Year mode uses coarse-to-fine refinement.
`meta.resolved_timezone`	Timezone actually used for local search timestamps.
`meta.scanned_candidates / coarse_candidates_scanned / refined_candidates_scanned / returned_candidates`	Search accounting across direct mode or year-mode refinement.
`meta.advisories`	Search-level warnings such as year-mode heuristics or omitted natal resonance.
`results[].event_time_local / event_time_utc`	Returned local event time plus the normalized UTC timestamp.
`results[].score_total / confidence_level / quality_band / status`	Comparative public ranking outcome for the searched window.
`results[].strict_traditional_verdict / strict_traditional_severity`	Separate doctrinal verdict and severity channel. A chart can rank best in-window while still being blemished or unsound.
`results[].comparative_window_rank / comparative_window_percentile / best_available_in_window`	How this candidate ranks against the full scanned set.
`results[].review_flags`	Flat machine-readable fact codes for UI filtering and QA.
`results[].hard_stops / supporting_factors / caution_factors`	Lists of astrological facts with scores and optional strict severity tags.
`results[].natal_resonance`	Optional bounded resonance block for attached natal subjects. Omitted when no natal data is supplied or birth time is unknown.