Astrocartography Parans

POST/api/v1/western/astrocartography/parans

Return classical in-mundo paran latitude bands, nearby cities, and deterministic interpretation fields for map overlays, relocation exploration, and hotspot UI.

Full URL

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

Classical Behavior

The paran endpoint is classical and in-mundo only. It does not expose projected mode.

Parans also require a known birth time, because the angular event math depends on the exact natal instant.

Request Body Parameters

Parameter	Type	Req	Description
`natal`	object	Yes	Same timed natal request block used across the astrocartography endpoints. Parans require known birth time and resolved coordinates.
`bodies`	array[string]	No	Optional subset of bodies to use for paran generation. Defaults to the live production body set including True Node.
`events`	array[string]	No	Optional subset of angular events. Supported values are "asc", "dsc", "mc", and "ic".
`min_abs_lat`	number	No	Minimum absolute latitude to search. Defaults to 0.0.
`max_abs_lat`	number	No	Maximum absolute latitude to search. Defaults to 66.0.
`limit`	integer	No	Maximum paran bands returned. The live example uses 20. Server cap is 300.
`paran_orb_deg`	number	No	Primary paran orb in degrees. The live production default is 1.0.
`paran_tail_deg`	number	No	Extended paran tail band in degrees. The live production default is 2.0.
`include_nearby_cities`	boolean	No	When true, each returned band includes up to three nearby cities. The live example uses the default behavior.

Sample Code

The request example below is the real live production test payload used on April 14, 2026, with the API key redacted.

curl -X POST "https://api.freeastroapi.com/api/v1/western/astrocartography/parans" \
 -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"
  },
  "limit": 20
}'

Real Response Example

This is a trimmed version of the real production response for the Paris test payload. Every field shown comes from the live API.

{
  "meta": {
    "mode": "in_mundo",
    "bodies": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars",
      "jupiter",
      "saturn",
      "uranus",
      "neptune",
      "pluto",
      "true_node"
    ],
    "events": ["asc", "dsc", "mc", "ic"],
    "timezone": "Europe/Paris",
    "paran_orb_deg": 1.0,
    "paran_tail_deg": 2.0,
    "geometry_format": "geojson",
    "coordinate_reference_system": "WGS84",
    "coordinate_order": "longitude_latitude",
    "count": 20
  },
  "warnings": [
    "Astrocartography results are exploratory and should be treated as directional rather than deterministic."
  ],
  "parans": [
    {
      "id": "sun:ic:jupiter:dsc:-21.105",
      "body_a": "sun",
      "event_a": "ic",
      "body_b": "jupiter",
      "event_b": "dsc",
      "latitude": -21.105,
      "orb_deg": 0.001,
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-180.0, -22.105],
          [180.0, -22.105],
          [180.0, -20.105],
          [-180.0, -20.105],
          [-180.0, -22.105]
        ]]
      },
      "nearest_cities": [
        {
          "name": "Ribeirão Preto",
          "country": "BR",
          "state": "Sao Paulo",
          "lat": -21.1775,
          "lng": -47.81028,
          "timezone": "America/Sao_Paulo",
          "population": 711825,
          "distance_km": 8.1
        },
        {
          "name": "Juiz de Fora",
          "country": "BR",
          "state": "Minas Gerais",
          "lat": -21.76417,
          "lng": -43.35028,
          "timezone": "America/Sao_Paulo",
          "population": 573285,
          "distance_km": 73.4
        }
      ],
      "strength": 1.0,
      "strongest_focus": "home",
      "secondary_focus": "health",
      "polarity": "supportive",
      "interpretation_short": "Sun IC with Jupiter DSC creates an expansion hotspot around 21.1° latitude. Best for home. Secondary pull: health.",
      "interpretation_caution": "Best use: expansion, confidence and recognition, while managing confidence can outrun realism, ego strain or burnout, excess or overreach.",
      "benefit_keywords": [
        "expansion",
        "confidence and recognition",
        "expansion and opportunity",
        "home and roots",
        "partnership and social mirroring",
        "home",
        "health"
      ],
      "risk_keywords": [
        "confidence can outrun realism",
        "ego strain or burnout",
        "excess or overreach",
        "mixed priorities"
      ]
    },
    {
      "id": "sun:mc:jupiter:asc:21.105",
      "body_a": "sun",
      "event_a": "mc",
      "body_b": "jupiter",
      "event_b": "asc",
      "latitude": 21.105,
      "orb_deg": 0.001,
      "...": "real response continues"
    },
    {
      "id": "sun:asc:jupiter:ic:51.254",
      "body_a": "sun",
      "event_a": "asc",
      "body_b": "jupiter",
      "event_b": "ic",
      "latitude": 51.254,
      "orb_deg": 0.0,
      "...": "real response continues"
    }
  ]
}

Response Fields

Field	Meaning
`meta.mode`	Always returns the classical paran mode used by the server. Live production currently returns `in_mundo`.
`meta.bodies`	Actual body list used after defaults and validation.
`meta.events`	Actual angular event list used after defaults and validation.
`meta.paran_orb_deg`	Resolved primary orb used for the calculation.
`meta.paran_tail_deg`	Resolved tail band used for the calculation.
`meta.geometry_format / coordinate_reference_system / coordinate_order`	Geometry contract metadata. Paran geometry is GeoJSON in WGS84 with lon/lat coordinate order.
`meta.count`	Number of paran bands returned in the payload.
`parans[].latitude`	The center latitude of the paran band.
`parans[].geometry`	GeoJSON `Polygon` band in WGS84 lon/lat order covering the paran orb around the center latitude.
`parans[].nearest_cities`	Nearby city matches for that latitude band when enabled.
`parans[].strongest_focus`	The strongest product focus inferred from the paran pair.
`parans[].secondary_focus`	Secondary focus that also scores well for the paran pair.
`parans[].polarity`	High-level support/challenge reading for the band.
`parans[].interpretation_short`	Short human-readable summary of what that paran combination emphasizes.