Astrocartography Recommendations

POST/api/v1/western/astrocartography/recommendations

Rank candidate cities for a specific relocation focus. The live response combines line, paran, and relocation-chart signals, then returns explainable scores, nearby line references, and optional map geometry for relocation-style apps.

Full URL

https://api.freeastroapi.com/api/v1/western/astrocartography/recommendations

How Ranking Works

Recommendation ranking is deterministic. The API scores candidate cities from the filtered pool, then labels the overall result quality with signal_strength, confidence, and match_tier.

The endpoint returns ranked cities even when matches are weak or mixed. It does not hide the ranking just because the top score is modest.

include_crossings defaults to false and requires High-plan access when enabled.

Request Body Parameters

Parameter	Type	Req	Description
`natal`	object	Yes	Same timed natal request block used across the Western endpoints. Recommendations require known birth time and resolved coordinates.
`focus`	string	Yes	Primary scoring focus. Live production supports "career", "romance", "home", "health", and "spiritual".
`country_scope`	string	No	Geographic scope selector. Supported values are "own_country", "selected_countries", and "all".
`country`	string	No	Optional single-country filter used with country-scoped searches.
`countries`	array[string]	No	Optional country-code list used with selected-country searches. The live example passes FR, ES, and PT.
`limit`	integer	No	Maximum number of ranked cities returned. The live example requests 10.
`min_population`	integer	No	Lower population bound for candidate cities. The live example uses 100000.
`max_population`	integer	No	Optional upper population bound for the candidate city pool.
`city_size`	string	No	Optional size bucket filter. Supported values are "small", "medium", "large", and "mega".
`mode`	string	No	Calculation mode. Defaults to "in_mundo". "projected" is also supported.
`bodies`	array[string]	No	Optional subset of bodies to use in scoring and optional map output.
`angles`	array[string]	No	Optional subset of "asc", "dsc", "mc", and "ic".
`topocentric`	boolean	No	Optional topocentric calculation mode. Defaults to false.
`nearby_radius_km`	number	No	Distance radius used when looking for nearby cities in the scoring flow. Defaults to 1000.0.
`paran_orb_deg`	number	No	Primary paran orb. Defaults to 1.0.
`paran_tail_deg`	number	No	Extended paran tail band. Defaults to 2.0.
`include_map_lines`	boolean	No	When true, the response includes a map-ready `map` block with line geometry. This is enabled in the live response example.
`include_crossings`	boolean	No	Defaults to false. Crossing enrichment is High-plan only because intersection discovery and hotspot interpretation are much heavier than plain ranking.
`include_paran_summary`	boolean	No	Controls whether paran detail blocks are included in each ranked result.
`include_relocation_summary`	boolean	No	Controls whether the lighter relocation summary block is included in each ranked result.

Sample Code

This request is the real live production payload used on April 14, 2026, with the API key redacted.

curl -X POST "https://api.freeastroapi.com/api/v1/western/astrocartography/recommendations" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
  "natal": {
    "year": 1995,
    "month": 9,
    "day": 5,
    "hour": 20,
    "minute": 0,
    "city": "Paris",
    "lat": 48.8566,
    "lng": 2.3522,
    "tz_str": "Europe/Paris",
    "time_known": true,
    "house_system": "placidus"
  },
  "focus": "home",
  "country_scope": "selected_countries",
  "countries": ["FR", "ES", "PT"],
  "limit": 10,
  "min_population": 100000
}'

Real Response Example

This is a trimmed version of the real production response. The ranking and field values are real. Repeated map geometry is abbreviated so the example stays readable in the docs.

{
  "meta": {
    "focus": "home",
    "mode": "in_mundo",
    "country_scope": "selected_countries",
    "city_size": null,
    "population_min": 100000,
    "population_max": null,
    "bodies": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars",
      "jupiter",
      "saturn",
      "uranus",
      "neptune",
      "pluto",
      "true_node"
    ],
    "angles": ["asc", "dsc", "mc", "ic"],
    "timezone": "Europe/Paris",
    "candidate_count": 79,
    "scored_count": 79,
    "signal_strength": "moderate",
    "confidence": "medium",
    "match_tier": "mixed",
    "no_strong_matches": false
  },
  "warnings": [
    "Astrocartography results are exploratory and should be treated as directional rather than deterministic."
  ],
  "results": [
    {
      "city": {
        "name": "Lille",
        "country": "FR",
        "state": "Hauts-de-France",
        "lat": 50.63391,
        "lng": 3.05512,
        "timezone": "Europe/Paris",
        "population": 238695
      },
      "distance_from_natal_km": 204.0,
      "score": 10.33,
      "summary": "No strong home lines were found, but the closest supportive line is Sun IC at about 6109.8 km.",
      "supporting_line_id": "sun:ic",
      "distance_to_line_km": 6109.8,
      "nearest_point_on_line": {
        "type": "Point",
        "coordinates": [89.683877, 50.63391]
      },
      "supporting_line_polarity": "mixed",
      "top_factors": [],
      "nearest_favorable_distance_km": 6109.8,
      "nearest_challenging_distance_km": 5912.5,
      "nearest_favorable_line": {
        "body": "sun",
        "angle": "ic",
        "line_id": "sun:ic",
        "distance_km": 6109.8,
        "nearest_point_on_line": {
          "type": "Point",
          "coordinates": [89.683877, 50.63391]
        }
      },
      "nearest_challenging_line": {
        "body": "saturn",
        "angle": "ic",
        "line_id": "saturn:ic",
        "distance_km": 5912.5,
        "nearest_point_on_line": {
          "type": "Point",
          "coordinates": [159.336799, 50.63391]
        }
      },
      "line_score": 0.0,
      "paran_score": 10.33,
      "relocation_score": 0.0,
      "top_parans": [
        {
          "id": "sun:asc:jupiter:ic:51.254",
          "body_a": "sun",
          "event_a": "asc",
          "body_b": "jupiter",
          "event_b": "ic",
          "latitude": 51.254,
          "distance_km": 69.0,
          "score": 9.87
        }
      ],
      "nearest_favorable_paran": {
        "id": "sun:asc:jupiter:ic:51.254",
        "body_a": "sun",
        "event_a": "asc",
        "body_b": "jupiter",
        "event_b": "ic",
        "latitude": 51.254,
        "distance_km": 69.0
      },
      "nearest_challenging_paran": null,
      "rank": 1,
      "relocation_summary": {
        "resolved_timezone": "Europe/Paris",
        "angles": {
          "asc": 332.074,
          "mc": 258.436,
          "ic": 78.436,
          "dc": 152.074
        },
        "angular_planets": [],
        "dominant_themes": [],
        "summary_short": "Relocated chart is not strongly angular for the tracked bodies.",
        "summary_caution": "No strong relocated angular pressure was detected."
      },
      "signal_strength": "moderate",
      "match_tier": "mixed"
    },
    {
      "city": {
        "name": "Gasteiz / Vitoria",
        "country": "ES",
        "state": "Basque Country",
        "lat": 42.84998,
        "lng": -2.67268,
        "timezone": "Europe/Madrid",
        "population": 257407
      },
      "distance_from_natal_km": 772.6,
      "score": 7.91,
      "summary": "No strong home lines were found, but the closest supportive line is Sun IC at about 7529.0 km.",
      "line_score": 0.0,
      "paran_score": 7.91,
      "relocation_score": 0.0,
      "top_parans": [
        {
          "id": "mercury:ic:uranus:dsc:42.879",
          "body_a": "mercury",
          "event_a": "ic",
          "body_b": "uranus",
          "event_b": "dsc",
          "latitude": 42.879,
          "distance_km": 3.2,
          "score": 7.91
        }
      ],
      "relocation_summary": {
        "resolved_timezone": "Europe/Madrid",
        "angular_planets": [
          {
            "body": "jupiter",
            "angle": "mc",
            "orb_deg": 5.87,
            "house": 9
          }
        ],
        "dominant_themes": ["career", "spiritual"],
        "summary_short": "Relocated chart emphasizes career, spiritual through Jupiter MC.",
        "summary_caution": "Main caution is balance: strong angular emphasis can still narrow life around a few themes."
      },
      "signal_strength": "moderate",
      "match_tier": "mixed"
    }
  ],
  "map": {
    "meta": {
      "geometry_format": "geojson",
      "coordinate_reference_system": "WGS84",
      "line_sample_step_degrees": 0.25,
      "crossing_count": 0
    },
    "...": "map line geometry continues when include_map_lines is enabled"
  }
}

Response Fields

Field	Meaning
`meta.focus`	Resolved focus used for the ranked search.
`meta.country_scope`	Resolved geographic scope after request validation.
`meta.population_min / meta.population_max`	Population filters that were actually applied to the candidate pool.
`meta.candidate_count / meta.scored_count`	How many candidate cities were considered and how many were scored.
`meta.signal_strength / meta.confidence / meta.match_tier`	Top-level quality labels for the returned ranking. These are useful when top matches are clustered or generally weak.
`meta.no_strong_matches`	Boolean flag indicating that the API did not find a clearly strong match for the chosen focus and filters.
`results[].city`	GeoService-shaped city payload with name, country, state, coordinates, timezone, and population.
`results[].score`	Raw total recommendation score used for ranking. It is the sum of line, paran, and relocation components.
`results[].line_score / results[].paran_score / results[].relocation_score`	Per-technique score breakdown for explainable ranking.
`results[].summary`	Short explanation suited to relocation UI cards or result lists.
`results[].supporting_line_id / distance_to_line_km / nearest_point_on_line / supporting_line_polarity`	Primary line link for the ranked city. This is the line the client can highlight directly on the map, with the nearest point already resolved.
`results[].top_parans`	Highest-impact nearby parans contributing to the score for that city.
`results[].nearest_favorable_line / results[].nearest_challenging_line`	Closest supportive and challenging line references used in the explanation layer. Each reference carries `line_id` plus a GeoJSON `nearest_point_on_line`.
`results[].relocation_summary`	Lighter relocation-chart summary with resolved timezone, angular planets, dominant themes, and short interpretation text.
`map`	Optional embedded GeoJSON line payload for drawing the same search on a world map when `include_map_lines` is enabled.