Purchase Car Electional API Docs

Purchase Car

Beta

POST/api/v2/western/electional/purchase-car/search

Search vehicle-purchase windows with emphasis on Mercury, the 3rd house, and paperwork clarity. The endpoint ranks candidate times for reliability, mobility, and low-friction execution while keeping doctrinal flags explicit.

Full URL

https://api.freeastroapi.com/api/v2/western/electional/purchase-car/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_purchase_car_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.
`buyer`	object	No	Buyer natal block used only for bounded resonance and tie-breaking. Alias `buyer_natal` is also accepted.
`buyer.name`	string	No	Display name. Defaults to "Buyer".
`buyer.year`	integer	Yes	Birth year.
`buyer.month`	integer	Yes	Birth month.
`buyer.day`	integer	Yes	Birth day.
`buyer.hour`	integer	No	Birth hour. Defaults to 12.
`buyer.minute`	integer	No	Birth minute. Defaults to 0.
`buyer.time_known`	boolean	No	Defaults to true. When false, natal resonance is omitted for that subject.
`buyer.city`	string	Conditional	Birth city. Required when natal coordinates are omitted.
`buyer.lat`	number	Conditional	Birth latitude. Required when natal city is omitted.
`buyer.lng`	number	Conditional	Birth longitude. Required when natal city is omitted.
`buyer.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/purchase-car/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/purchase-car/search",
    "scoring_version": "clean_room_purchase_car_v1",
    "calibration_version": "internal_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-01T10:00:00+02:00",
      "event_time_utc": "2026-06-01T08:00:00Z",
      "score_total": 16,
      "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"
      ],
      "hard_stops": [
        {
          "code": "moon_void_of_course_stop",
          "title": "Moon void of course",
          "score": 0,
          "detail": "Moon void of course",
          "severity": "major"
        }
      ],
      "supporting_factors": [
        {
          "code": "mercury_dignified",
          "title": "Mercury dignified",
          "score": 8,
          "detail": "Mercury dignified"
        },
        {
          "code": "mercury_direct",
          "title": "Mercury direct",
          "score": 6,
          "detail": "Mercury direct"
        },
        {
          "code": "mercury_unafflicted",
          "title": "Mercury free from hard malefic pressure",
          "score": 6,
          "detail": "Mercury free from hard malefic pressure"
        },
        {
          "code": "mercury_supportive_house",
          "title": "Mercury in a mobility-supportive house",
          "score": 5,
          "detail": "Mercury in a mobility-supportive house"
        }
      ],
      "caution_factors": [
        {
          "code": "out_of_sect_malefic_angular",
          "title": "Out-of-sect malefic angular",
          "score": -5,
          "detail": "Out-of-sect malefic angular"
        },
        {
          "code": "moon_waning",
          "title": "Waning Moon",
          "score": -3,
          "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.