Astrocartography City Check

POST/api/v1/western/astrocartography/city-check

Score one city for one person across all public astrocartography focuses at once. This is the endpoint to use when a client already knows the destination and needs a detailed breakdown instead of a ranked search.

Full URL

https://api.freeastroapi.com/api/v1/western/astrocartography/city-check

What This Endpoint Returns

city-check evaluates one location across the five public focuses in a single call: career, romance, home, health, and spiritual.

The response exposes raw scores and score components. It does not collapse everything into a single normalized consumer rating.

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. City check requires known birth time and resolved coordinates.
`city`	string	Yes	Target city name to evaluate for the person. The live example checks Lisbon.
`country`	string	No	Optional country code to disambiguate the target city lookup. The live example passes PT.
`lat / lng`	number / number	No	Optional direct coordinates for the target city when you want to bypass or constrain place lookup.
`mode`	string	No	Calculation mode. Defaults to "in_mundo". "projected" is also supported.
`bodies`	array[string]	No	Optional subset of bodies to use in the city evaluation.
`angles`	array[string]	No	Optional subset of "asc", "dsc", "mc", and "ic".
`topocentric`	boolean	No	Optional topocentric calculation mode. Defaults to false.
`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	Defaults to true. When enabled, the response includes a `map` block with line geometry for drawing the city context on a map.
`include_crossings`	boolean	No	Defaults to false. Crossing enrichment is High-plan only.
`include_paran_summary`	boolean	No	Controls whether paran detail blocks are included in each focus score.
`include_relocation_summary`	boolean	No	Controls whether the top-level relocation summary is included in the payload.

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/city-check" \
 -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"
  },
  "city": "Lisbon",
  "country": "PT"
}'

Real Response Example

This is a trimmed version of the real production response for Lisbon. The score values are real. Repeated map geometry and repeated focus blocks are abbreviated for readability.

{
  "city": {
    "name": "Lisbon",
    "country": "PT",
    "state": "Lisbon",
    "lat": 38.72509,
    "lng": -9.1498,
    "timezone": "Europe/Lisbon",
    "population": 517802
  },
  "overall_score": 58.46,
  "focus_scores": {
    "career": {
      "score": 151.55,
      "summary": "Jupiter MC is the strongest supportive line for this career search, with 3 nearby contributing line(s).",
      "top_factors": [
        {
          "line_id": "jupiter:mc",
          "body": "jupiter",
          "angle": "mc",
          "distance_km": 26.0,
          "nearest_point_on_line": {
            "type": "Point",
            "coordinates": [22.078336, 38.72509]
          },
          "weight": 1.25,
          "score": 123.91,
          "polarity": "supportive"
        },
        {
          "line_id": "pluto:mc",
          "body": "pluto",
          "angle": "mc",
          "distance_km": 562.4,
          "nearest_point_on_line": {
            "type": "Point",
            "coordinates": [3.930579, 38.72509]
          },
          "weight": -0.85,
          "score": -7.54,
          "polarity": "challenging"
        }
      ],
      "nearest_favorable_distance_km": 26.0,
      "nearest_challenging_distance_km": 562.4,
      "nearest_favorable_line": {
        "body": "jupiter",
        "angle": "mc",
        "line_id": "jupiter:mc",
        "distance_km": 26.0,
        "nearest_point_on_line": {
          "type": "Point",
          "coordinates": [22.078336, 38.72509]
        }
      },
      "nearest_challenging_line": {
        "body": "pluto",
        "angle": "mc",
        "line_id": "pluto:mc",
        "distance_km": 562.4,
        "nearest_point_on_line": {
          "type": "Point",
          "coordinates": [3.930579, 38.72509]
        }
      },
      "supporting_line_id": "jupiter:mc",
      "distance_to_line_km": 26.0,
      "nearest_point_on_line": {
        "type": "Point",
        "coordinates": [22.078336, 38.72509]
      },
      "supporting_line_polarity": "supportive",
      "line_score": 115.72,
      "paran_score": -6.83,
      "relocation_score": 42.66,
      "top_parans": [
        {
          "id": "jupiter:asc:saturn:ic:38.902",
          "body_a": "jupiter",
          "event_a": "asc",
          "body_b": "saturn",
          "event_b": "ic",
          "latitude": 38.902,
          "distance_km": 19.7,
          "score": -6.83
        }
      ],
      "nearest_favorable_paran": null,
      "nearest_challenging_paran": {
        "id": "jupiter:asc:saturn:ic:38.902",
        "body_a": "jupiter",
        "event_a": "asc",
        "body_b": "saturn",
        "event_b": "ic",
        "latitude": 38.902,
        "distance_km": 19.7
      }
    },
    "home": {
      "score": -16.64,
      "summary": "No strong home lines were found, but the closest supportive line is Sun IC at about 8573.8 km.",
      "top_factors": [],
      "nearest_favorable_distance_km": 8573.8,
      "nearest_challenging_distance_km": 6213.6,
      "nearest_favorable_line": {
        "body": "sun",
        "angle": "ic",
        "line_id": "sun:ic",
        "distance_km": 8573.8,
        "nearest_point_on_line": {
          "type": "Point",
          "coordinates": [89.683877, 38.72509]
        }
      },
      "nearest_challenging_line": {
        "body": "saturn",
        "angle": "ic",
        "line_id": "saturn:ic",
        "distance_km": 6213.6,
        "nearest_point_on_line": {
          "type": "Point",
          "coordinates": [159.336799, 38.72509]
        }
      },
      "supporting_line_id": "sun:ic",
      "distance_to_line_km": 8573.8,
      "nearest_point_on_line": {
        "type": "Point",
        "coordinates": [89.683877, 38.72509]
      },
      "supporting_line_polarity": "mixed",
      "line_score": 0.0,
      "paran_score": -16.64,
      "relocation_score": 0.0,
      "top_parans": [
        {
          "id": "jupiter:asc:saturn:ic:38.902",
          "body_a": "jupiter",
          "event_a": "asc",
          "body_b": "saturn",
          "event_b": "ic",
          "latitude": 38.902,
          "distance_km": 19.7,
          "score": -17.08
        }
      ],
      "nearest_favorable_paran": {
        "id": "mercury:ic:neptune:dsc:37.262",
        "body_a": "mercury",
        "event_a": "ic",
        "body_b": "neptune",
        "event_b": "dsc",
        "latitude": 37.262,
        "distance_km": 162.9
      },
      "nearest_challenging_paran": {
        "id": "jupiter:asc:saturn:ic:38.902",
        "body_a": "jupiter",
        "event_a": "asc",
        "body_b": "saturn",
        "event_b": "ic",
        "latitude": 38.902,
        "distance_km": 19.7
      }
    },
    "spiritual": {
      "score": 132.36,
      "summary": "Jupiter MC is the strongest supportive line for this spiritual search, with 3 nearby contributing line(s).",
      "line_score": 82.85,
      "paran_score": 27.33,
      "relocation_score": 22.18,
      "top_parans": [
        {
          "id": "jupiter:asc:saturn:ic:38.902",
          "body_a": "jupiter",
          "event_a": "asc",
          "body_b": "saturn",
          "event_b": "ic",
          "latitude": 38.902,
          "distance_km": 19.7,
          "score": 27.33
        }
      ]
    },
    "...": "live response also includes romance and health focus blocks"
  },
  "relocation_summary": {
    "resolved_timezone": "Europe/Lisbon",
    "angles": {
      "asc": 320.812,
      "mc": 247.047,
      "ic": 67.047,
      "dc": 140.812
    },
    "angular_planets": [
      {
        "body": "jupiter",
        "angle": "mc",
        "orb_deg": 0.2,
        "house": 10
      }
    ],
    "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."
  },
  "map": {
    "meta": {
      "mode": "in_mundo",
      "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
`city`	Resolved target city payload with name, country, state, coordinates, timezone, and population.
`overall_score`	Aggregate raw score across the public focuses. This is a whole-city summary, not a normalized rating band.
`focus_scores`	Per-focus breakdown for career, romance, home, health, and spiritual. Each block is independently scored.
`focus_scores.{focus}.score`	Raw score for that focus in the checked city.
`focus_scores.{focus}.line_score / paran_score / relocation_score`	Technique-level explanation of where the focus score comes from.
`focus_scores.{focus}.top_factors`	Nearest and highest-impact line contributions used in the explanation layer. Each factor includes `line_id`, a GeoJSON `nearest_point_on_line`, and polarity.
`focus_scores.{focus}.supporting_line_id / distance_to_line_km / nearest_point_on_line / supporting_line_polarity`	Primary line link for that focus. This lets the client highlight the chosen line directly without recomputing nearest geometry.
`focus_scores.{focus}.top_parans`	Nearby paran bands that materially affect that focus.
`focus_scores.{focus}.nearest_favorable_line / nearest_challenging_line`	Closest supportive and challenging line references for that focus. Each carries `line_id` plus a GeoJSON `nearest_point_on_line`.
`focus_scores.{focus}.nearest_favorable_paran / nearest_challenging_paran`	Closest supportive and challenging paran references for that focus when present.
`relocation_summary`	Top-level relocation-chart summary for the checked city, including resolved timezone, angles, angular planets, dominant themes, and short interpretation text.
`map`	Optional embedded GeoJSON line geometry payload for map rendering when `include_map_lines` is enabled.