Purchase Property Electional API Docs

Purchase Property

Beta

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

Search property-acquisition windows with emphasis on the 2nd and 4th houses, domestic durability, and financial steadiness. The endpoint ranks candidate windows and surfaces doctrinal blemishes separately from comparative recommendation.

Full URL

https://api.freeastroapi.com/api/v2/western/electional/purchase-property/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_property_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-property/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-property/search",
    "scoring_version": "clean_room_purchase_property_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-01T14:00:00+02:00",
      "event_time_utc": "2026-06-01T12:00:00Z",
      "score_total": 14,
      "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": "h4_ruler_dignified",
          "title": "4th ruler dignified",
          "score": 6,
          "detail": "4th ruler dignified"
        },
        {
          "code": "moon_supportive_house",
          "title": "Moon in a home-supportive house",
          "score": 5,
          "detail": "Moon in a home-supportive house"
        },
        {
          "code": "venus_supportive_house",
          "title": "Venus in a home-supportive house",
          "score": 5,
          "detail": "Venus in a home-supportive house"
        },
        {
          "code": "h4_ruler_supportive_house",
          "title": "Jupiter in a home-supportive house",
          "score": 5,
          "detail": "Jupiter in a home-supportive house"
        }
      ],
      "caution_factors": [
        {
          "code": "venus_malefic_pressure",
          "title": "Venus under hard malefic pressure",
          "score": -5,
          "detail": "Venus under hard malefic pressure"
        },
        {
          "code": "h2_ruler_malefic_pressure",
          "title": "2nd ruler under hard malefic pressure",
          "score": -5,
          "detail": "2nd ruler under hard malefic pressure"
        },
        {
          "code": "saturn_pressures_h2",
          "title": "Saturn pressures 2nd ruler",
          "score": -5,
          "detail": "Saturn pressures 2nd ruler, orb 3.70"
        },
        {
          "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.