Astrocartography Lines

POST/api/v1/western/astrocartography/lines

Return dense WGS84 GeoJSON line geometry for world maps. The live production payload exposes every astrocartography line as a directly renderable LineString or MultiLineStringin lon/lat order.

Full URL

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

Plan and Access

Plain line geometry is available on standard plans. The live default request does not include crossings.

include_crossings defaults to false. When set to true, the endpoint requires High plan access and returns a `403 high_plan_required` error for free-tier callers.

Request Body Parameters

Parameter	Type	Req	Description
`natal`	object	Yes	Same timed natal request block used by the Western endpoints. Astrocartography requires known birth time and resolved coordinates.
`mode`	string	No	Defaults to "in_mundo". "projected" is also supported for line generation.
`bodies`	array[string]	No	Optional subset of bodies to calculate. Defaults to the live production set: Sun through Pluto plus True Node.
`angles`	array[string]	No	Optional subset of "asc", "dsc", "mc", and "ic". All four are returned by default.
`topocentric`	boolean	No	Optional topocentric calculation mode. Defaults to false.
`include_crossings`	boolean	No	Defaults to false. When true, the endpoint attempts line intersection discovery and premium hotspot enrichment. This is High-plan only.

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/lines" \
 -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"
  }
}'

Real Response Example

This is a trimmed version of the real production response for the Paris test payload. Repeated horizon points are omitted for readability, but every shown field and value comes from the live API.

{
  "meta": {
    "mode": "in_mundo",
    "bodies": [
      "sun",
      "moon",
      "mercury",
      "venus",
      "mars",
      "jupiter",
      "saturn",
      "uranus",
      "neptune",
      "pluto",
      "true_node"
    ],
    "angles": ["asc", "dsc", "mc", "ic"],
    "timezone": "Europe/Paris",
    "geometry_format": "geojson",
    "coordinate_reference_system": "WGS84",
    "coordinate_order": "longitude_latitude",
    "line_sample_step_degrees": 0.25,
    "crossing_count": 0
  },
  "warnings": [
    "Astrocartography results are exploratory and should be treated as directional rather than deterministic."
  ],
  "lines": [
    {
      "id": "sun:asc",
      "body": "sun",
      "angle": "asc",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-156.218897, -68.75],
          [-151.470534, -68.5],
          [-148.257733, -68.25],
          [-145.683564, -68.0],
          "... dense WGS84 lon/lat coordinates continue ...",
          [179.713656, 0.0],
          [179.683877, 0.25],
          [179.654093, 0.5]
        ]
      }
    },
    {
      "id": "sun:mc",
      "body": "sun",
      "angle": "mc",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-90.316123, -89.0],
          [-90.316123, -88.75],
          [-90.316123, -88.5],
          "...",
          [-90.316123, 88.75],
          [-90.316123, 89.0]
        ]
      }
    }
  ],
  "crossings": []
}

Response Fields

Field	Meaning
`meta.mode`	Resolved astrocartography mode for the response.
`meta.bodies`	Actual body list used by the server after defaults and validation.
`meta.angles`	Actual angle list used by the server after defaults and validation.
`meta.timezone`	Resolved timezone used to derive the natal instant.
`meta.geometry_format / coordinate_reference_system / coordinate_order`	Geometry contract metadata. The line payload is GeoJSON in WGS84 with lon/lat coordinate order.
`meta.line_sample_step_degrees`	Dense sampling interval used to make the returned line geometry directly renderable on a 2D map.
`meta.crossing_count`	Number of crossings attached to the payload. This stays 0 when crossings are not requested.
`warnings`	Interpretive or geometry warnings. The live response includes the exploratory-use caveat by default.
`lines[].geometry`	Full WGS84 GeoJSON line geometry. The server returns a `LineString` when the path is continuous and a `MultiLineString` when it must be split around the date line or real discontinuities.
`crossings`	Present in the payload but empty by default. Real crossing data is only returned when `include_crossings=true` and the caller has High-plan access. Each crossing carries a GeoJSON `geometry` point plus the paired lines and interpretation fields.

Premium Gate Example

This is the real live `403` returned on April 14, 2026 when the same endpoint was called with include_crossings=true using a free-tier API key.

{
  "detail": {
    "error": "high_plan_required",
    "message": "Astrocartography crossings require the High plan because intersection discovery and hotspot enrichment consume significantly more compute than plain line generation.",
    "required_plan": "High",
    "current_plan": "Free",
    "upgrade_required": true,
    "endpoint": "/api/v1/western/astrocartography/lines"
  }
}