---
title: "Calculate astrocartography geometry and optional downloadable maps"
method: POST
path: "/api/astro/astrocartography"
tags: ["Calculations"]
---

# Calculate astrocartography geometry and optional downloadable maps

`POST /api/astro/astrocartography`

## Request

- Base URL: `https://api.cosmicephemeris.com`
- URL: `https://api.cosmicephemeris.com/api/astro/astrocartography`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Returns MC and IC meridians plus sampled geometric rising and setting curves for 1-10 selected DE440 bodies. Set include_geojson true for a deterministic RFC 7946 FeatureCollection with four ordered features per body. Set include_geojson_seq true for the same ordered features as a deterministic RFC 8142 GeoJSON Text Sequence. Set include_ndjson true for those features as deterministic LF-terminated newline-delimited JSON records. Set include_topojson true for deterministic unquantized TopoJSON with a named GeometryCollection and central arc inventory. Set include_kml true for a deterministic OGC KML 2.2 artifact with four ordered placemarks per body and integrity metadata. Set include_gpx true for a deterministic GPX 1.1 artifact with four ordered tracks per body and preserved date-line track segments. Set include_csv true for deterministic RFC 4180 rows that preserve every authoritative geometry point and date-line segment. Set include_wkt true for one deterministic WKT GEOMETRYCOLLECTION with fixed geometry ordering and preserved date-line segments. Set include_wkb true for the same collection as deterministic OGC WKB 1.x little-endian binary. Set include_gml true for deterministic GML 3.2 in a CRS84 MultiGeometry with preserved date-line curves. Set include_svg true for a deterministic 1200x800 coordinate-grid map and include_png true for its PNG derivative. Light, dark and monochrome themes are supported. Curves use a fixed two-degree calculation grid from -88 through +88 and split at the date line; the visual renderer connects fixed four-degree display samples. Set basemap natural-earth-110m with include_svg true for bundled public-domain coastline v4.1.0 and pinned provenance; default coordinate-grid-only is unchanged. No runtime map fetches, arbitrary sampling, map tiles, political boundaries, refraction, terrain, interpretation, ranking or recommended places are provided. One standard quota unit per admitted request, including any export; failed or timed-out admitted attempts are not refunded.
Historical mode uses an explicit BCE/CE date object and UT1 conventions. Its response is the versioned historical envelope, not the modern UTC envelope. Read result for calculation fields and metadata for limits and uncertainty.

## Request body

- union
  - AstrocartographyRequest
    - `at` CivilTimeInput, required
      - `date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
      - `time` string, required: HH:MM or HH:MM:SS; no offset in this field. Use timezone to select the civil-time zone.
      - `timezone` string
    - `bodies` AstrocartographyBody[], required
    - `include_svg` boolean: When true, returns a deterministic 1200x800 Cosmic Ephemeris-owned coordinate-grid SVG map. Omission or false preserves the predecessor geometry response exactly.
    - `basemap` 'coordinate-grid-only' | 'natural-earth-110m': Requires include_svg true. Natural Earth adds a bundled public-domain 1:110m coastline with pinned provenance; no tiles, network calls, navigation accuracy, boundaries, geocoding or change to angular geometry. Omission preserves the predecessor output.
    - `include_png` boolean: When true, also returns a deterministic PNG derived from the returned SVG. Requires include_svg true.
    - `theme` 'light' | 'dark' | 'monochrome': Map theme. Requires include_svg true.
    - `include_geojson` boolean: When true, returns a deterministic RFC 7946 FeatureCollection with four ordered features per body. Independent of SVG/PNG export.
    - `include_geojson_seq` boolean: When true, returns a deterministic RFC 8142 GeoJSON Text Sequence with four ordered Feature records per body. Independent of every other export.
    - `include_ndjson` boolean: When true, returns deterministic newline-delimited compact RFC 7946 Feature records in body/angle order. Independent of every other export.
    - `include_topojson` boolean: When true, returns deterministic unquantized TopoJSON with one named GeometryCollection, a central arc inventory, and exact authoritative coordinates. Independent of every other export.
    - `include_kml` boolean: When true, returns a deterministic OGC KML 2.2 artifact with four ordered placemarks per body, fixed integrity metadata, and exact authoritative coordinates. Independent of GeoJSON and SVG/PNG export.
    - `include_gpx` boolean: When true, returns a deterministic GPX 1.1 artifact with four ordered tracks per body, preserved date-line track segments, fixed integrity metadata, and exact authoritative coordinates. Independent of GeoJSON, KML, and SVG/PNG export.
    - `include_csv` boolean: When true, returns a deterministic RFC 4180 CSV artifact with one fixed-column row per authoritative geometry point in body, MC, IC, ascendant, descendant, segment, and point order. Independent of every other export.
    - `include_wkt` boolean: When true, returns one deterministic WKT GEOMETRYCOLLECTION with four ordered geometries per body and preserved date-line segments. Independent of every other export.
    - `include_wkb` boolean: When true, returns one deterministic OGC WKB 1.x little-endian GEOMETRYCOLLECTION with four ordered geometries per body and preserved date-line segments. Independent of every other export.
    - `include_gml` boolean: When true, returns one deterministic GML 3.2 MultiGeometry in CRS84 with four ordered geometries per body and preserved date-line segments. Independent of every other export.
  - HistoricalAstrocartographyRequest: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
    - `at` HistoricalDateTime, required: Shared historical input contract; parsing alone does not enable a calculation route. Derived calculation records can include fractional seconds and are not this input type.
      - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
        - `year` integer, required
        - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
        - `month` integer, required
        - `day` integer, required
        - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
      - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
      - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
    - `bodies` string[], required
    - `include_svg` boolean: When true, returns a deterministic 1200x800 Cosmic Ephemeris-owned coordinate-grid SVG map. Omission or false preserves the predecessor geometry response exactly.
    - `basemap` 'coordinate-grid-only' | 'natural-earth-110m': Requires include_svg true. Natural Earth adds a bundled public-domain 1:110m coastline with pinned provenance; no tiles, network calls, navigation accuracy, boundaries, geocoding or change to angular geometry. Omission preserves the predecessor output.
    - `include_png` boolean: When true, also returns a deterministic PNG derived from the returned SVG. Requires include_svg true.
    - `theme` 'light' | 'dark' | 'monochrome': Map theme. Requires include_svg true.
    - `include_geojson` boolean: When true, returns a deterministic RFC 7946 FeatureCollection with four ordered features per body. Independent of SVG/PNG export.
    - `include_geojson_seq` boolean: When true, returns a deterministic RFC 8142 GeoJSON Text Sequence with four ordered Feature records per body. Independent of every other export.
    - `include_ndjson` boolean: When true, returns deterministic newline-delimited compact RFC 7946 Feature records in body/angle order. Independent of every other export.
    - `include_topojson` boolean: When true, returns deterministic unquantized TopoJSON with one named GeometryCollection, a central arc inventory, and exact authoritative coordinates. Independent of every other export.
    - `include_kml` boolean: When true, returns a deterministic OGC KML 2.2 artifact with four ordered placemarks per body, fixed integrity metadata, and exact authoritative coordinates. Independent of GeoJSON and SVG/PNG export.
    - `include_gpx` boolean: When true, returns a deterministic GPX 1.1 artifact with four ordered tracks per body, preserved date-line track segments, fixed integrity metadata, and exact authoritative coordinates. Independent of GeoJSON, KML, and SVG/PNG export.
    - `include_csv` boolean: When true, returns a deterministic RFC 4180 CSV artifact with one fixed-column row per authoritative geometry point in body, MC, IC, ascendant, descendant, segment, and point order. Independent of every other export.
    - `include_wkt` boolean: When true, returns one deterministic WKT GEOMETRYCOLLECTION with four ordered geometries per body and preserved date-line segments. Independent of every other export.
    - `include_wkb` boolean: When true, returns one deterministic OGC WKB 1.x little-endian GEOMETRYCOLLECTION with four ordered geometries per body and preserved date-line segments. Independent of every other export.
    - `include_gml` boolean: When true, returns one deterministic GML 3.2 MultiGeometry in CRS84 with four ordered geometries per body and preserved date-line segments. Independent of every other export.

## Response `200`

Bounded angular-line geometry using signed longitudes, with optional deterministic GeoJSON, GeoJSON Text Sequences, NDJSON, TopoJSON, KML, GPX, CSV, WKT, WKB, GML, and SVG/PNG map exports.

- union
  - AstrocartographyResponse
    - `type` 'astrocartography', required
    - `status` 'current', required
    - `method` 'apparent_geocentric_equatorial_angular_lines', required
    - `input` object, required
    - `utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
    - `lines` AstrocartographyLine[], required
      - `body` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
      - `equatorial` object, required
        - `right_ascension_degrees` number, required
        - `declination_degrees` number, required
      - `mc` object, required
        - `longitude` number, required
      - `ic` object, required
        - `longitude` number, required
      - `ascendant` object, required
        - `segments` array[], required
          - AstrocartographyPoint[]
            - `latitude` number, required
            - `longitude` number, required
      - `descendant` object, required
        - `segments` array[], required
          - AstrocartographyPoint[]
            - `latitude` number, required
            - `longitude` number, required
    - `metadata` object, required
    - `svg` string: Present only when include_svg is true. Standalone coordinate-grid SVG or opt-in bundled Natural Earth coastline, without runtime external resources. Coastline metadata includes provider, version, source/artifact SHA-256, public-domain terms and attribution.
    - `theme` 'light' | 'dark' | 'monochrome': Present only with svg.
    - `png` PngExport: Deterministic, metadata-free PNG rendered from Cosmic Ephemeris's own SVG primitive subset. No uploaded SVG, URL, font, browser, or external rendering service is accepted.
      - `media_type` 'image/png', required
      - `base64` string, required: Base64-encoded PNG bytes; decode as an image, never HTML.
      - `bytes` integer, required
      - `sha256` string, required
      - `width` 1200, required
      - `height` 800 | 1100 | 1120 | 1420, required
      - `renderer` 'cosmicephemeris-original-png-v1', required
      - `source_svg_sha256` string, required
    - `geojson` AstrocartographyGeoJson: Present only when include_geojson is true. Features preserve request body order and repeat MC, IC, ascendant, descendant order for every body.
      - `type` 'FeatureCollection', required
      - `features` AstrocartographyGeoJsonFeature[], required
        - `type` 'Feature', required
        - `id` string, required
        - `properties` object, required
          - `body` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
          - `angle` 'mc' | 'ic' | 'ascendant' | 'descendant', required
        - `geometry` union, required
          - object
            - `type` 'LineString', required
            - `coordinates` GeoJsonPosition[], required
              - …
          - object
            - `type` 'MultiLineString', required
            - `coordinates` array[], required
              - …
    - `geojson_seq` AstrocartographyGeoJsonSequenceExport: Present only when include_geojson_seq is true. Base64 decodes to deterministic RFC 8142 GeoJSON Text Sequences: one RS-prefixed compact RFC 7946 Feature and LF terminator per record, in requested body then MC, IC, ascendant, descendant order. No artifact is persisted.
      - `filename` 'cosmicephemeris-astrocartography.geojson-seq', required
      - `media_type` 'application/geo+json-seq', required
      - `encoding` 'base64', required
      - `bytes` integer, required
      - `sha256` string, required
      - `base64` string, required
    - `ndjson` AstrocartographyNdjsonExport: Present only when include_ndjson is true. Base64 decodes to one compact RFC 7946 Feature per LF-terminated line, in requested body then MC, IC, ascendant, descendant order. No artifact is persisted.
      - `filename` 'cosmicephemeris-astrocartography.ndjson', required
      - `media_type` 'application/x-ndjson', required
      - `encoding` 'base64', required
      - `bytes` integer, required
      - `sha256` string, required
      - `base64` string, required
    - `topojson` AstrocartographyTopoJsonExport: Present only when include_topojson is true. Base64 decodes to deterministic unquantized TopoJSON with a named astrocartography GeometryCollection and exact coordinates. application/json is used because application/topo+json is not an IANA-registered media type. No artifact is persisted.
      - `filename` 'cosmicephemeris-astrocartography.topojson', required
      - `media_type` 'application/json', required
      - `encoding` 'base64', required
      - `bytes` integer, required
      - `sha256` string, required
      - `base64` string, required
    - `kml` AstrocartographyKmlExport: Present only when include_kml is true. Base64 decodes to deterministic OGC KML 2.2 with four ordered placemarks per body and exact authoritative angular-line coordinates. No artifact is persisted.
      - `filename` 'cosmicephemeris-astrocartography.kml', required
      - `media_type` 'application/vnd.google-earth.kml+xml', required
      - `encoding` 'base64', required
      - `bytes` integer, required
      - `sha256` string, required
      - `base64` string, required
    - `gpx` AstrocartographyGpxExport: Present only when include_gpx is true. Base64 decodes to deterministic GPX 1.1 with four ordered tracks per body, date-line segment preservation, and exact authoritative angular-line coordinates. No artifact is persisted.
      - `filename` 'cosmicephemeris-astrocartography.gpx', required
      - `media_type` 'application/gpx+xml', required
      - `encoding` 'base64', required
      - `bytes` integer, required
      - `sha256` string, required
      - `base64` string, required
    - `csv` AstrocartographyCsvExport: Present only when include_csv is true. Base64 decodes to deterministic UTF-8 RFC 4180 CSV with CRLF records, one fixed header, and one row per authoritative geometry point. Segment and point indexes are one-based. No artifact is persisted.
      - `filename` 'cosmicephemeris-astrocartography.csv', required
      - `media_type` 'text/csv; charset=utf-8', required
      - `encoding` 'base64', required
      - `bytes` integer, required
      - `sha256` string, required
      - `base64` string, required
    - `wkt` AstrocartographyWktExport: Present only when include_wkt is true. Base64 decodes to one deterministic UTF-8 WKT GEOMETRYCOLLECTION in requested body then MC, IC, ascendant, descendant order. MC/IC are LINESTRING; rising/setting are MULTILINESTRING so date-line segments remain distinct. No artifact is persisted.
      - `filename` 'cosmicephemeris-astrocartography.wkt', required
      - `media_type` 'text/plain; charset=utf-8', required
      - `encoding` 'base64', required
      - `bytes` integer, required
      - `sha256` string, required
      - `base64` string, required
    - `wkb` AstrocartographyWkbExport: Present only when include_wkb is true. Base64 decodes to one deterministic OGC WKB 1.x little-endian two-dimensional GEOMETRYCOLLECTION in requested body then MC, IC, ascendant, descendant order. MC/IC are LINESTRING; rising/setting are MULTILINESTRING so date-line segments remain distinct. It has no SRID, EWKB flags, Z/M coordinates, properties, or labels. No artifact is persisted.
      - `filename` 'cosmicephemeris-astrocartography.wkb', required
      - `media_type` 'application/octet-stream', required
      - `encoding` 'base64', required
      - `bytes` integer, required
      - `sha256` string, required
      - `base64` string, required
    - `gml` AstrocartographyGmlExport: Present only when include_gml is true. Base64 decodes to deterministic UTF-8 GML 3.2 using one CRS84 MultiGeometry in requested body then MC, IC, ascendant, descendant order. MC/IC are LineString; rising/setting are MultiCurve so date-line segments remain distinct. IDs and coordinates derive only from authoritative output. No artifact is persisted.
      - `filename` 'cosmicephemeris-astrocartography.gml', required
      - `media_type` 'application/gml+xml; version=3.2', required
      - `encoding` 'base64', required
      - `bytes` integer, required
      - `sha256` string, required
      - `base64` string, required
  - HistoricalAstrocartographyAstrocartographyResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'astrocartography', required
    - `input` HistoricalAstrocartographyRequest, required: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
      - `at` HistoricalDateTime, required: Shared historical input contract; parsing alone does not enable a calculation route. Derived calculation records can include fractional seconds and are not this input type.
        - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
          - `year` integer, required
          - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
          - `month` integer, required
          - `day` integer, required
          - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
        - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
        - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
      - `bodies` string[], required
      - `include_svg` boolean: When true, returns a deterministic 1200x800 Cosmic Ephemeris-owned coordinate-grid SVG map. Omission or false preserves the predecessor geometry response exactly.
      - `basemap` 'coordinate-grid-only' | 'natural-earth-110m': Requires include_svg true. Natural Earth adds a bundled public-domain 1:110m coastline with pinned provenance; no tiles, network calls, navigation accuracy, boundaries, geocoding or change to angular geometry. Omission preserves the predecessor output.
      - `include_png` boolean: When true, also returns a deterministic PNG derived from the returned SVG. Requires include_svg true.
      - `theme` 'light' | 'dark' | 'monochrome': Map theme. Requires include_svg true.
      - `include_geojson` boolean: When true, returns a deterministic RFC 7946 FeatureCollection with four ordered features per body. Independent of SVG/PNG export.
      - `include_geojson_seq` boolean: When true, returns a deterministic RFC 8142 GeoJSON Text Sequence with four ordered Feature records per body. Independent of every other export.
      - `include_ndjson` boolean: When true, returns deterministic newline-delimited compact RFC 7946 Feature records in body/angle order. Independent of every other export.
      - `include_topojson` boolean: When true, returns deterministic unquantized TopoJSON with one named GeometryCollection, a central arc inventory, and exact authoritative coordinates. Independent of every other export.
      - `include_kml` boolean: When true, returns a deterministic OGC KML 2.2 artifact with four ordered placemarks per body, fixed integrity metadata, and exact authoritative coordinates. Independent of GeoJSON and SVG/PNG export.
      - `include_gpx` boolean: When true, returns a deterministic GPX 1.1 artifact with four ordered tracks per body, preserved date-line track segments, fixed integrity metadata, and exact authoritative coordinates. Independent of GeoJSON, KML, and SVG/PNG export.
      - `include_csv` boolean: When true, returns a deterministic RFC 4180 CSV artifact with one fixed-column row per authoritative geometry point in body, MC, IC, ascendant, descendant, segment, and point order. Independent of every other export.
      - `include_wkt` boolean: When true, returns one deterministic WKT GEOMETRYCOLLECTION with four ordered geometries per body and preserved date-line segments. Independent of every other export.
      - `include_wkb` boolean: When true, returns one deterministic OGC WKB 1.x little-endian GEOMETRYCOLLECTION with four ordered geometries per body and preserved date-line segments. Independent of every other export.
      - `include_gml` boolean: When true, returns one deterministic GML 3.2 MultiGeometry in CRS84 with four ordered geometries per body and preserved date-line segments. Independent of every other export.
    - `result` object, required: Complete historical calculation adapter result. Times are explicit UT1 date records, never UTC strings; derived times may include fractional seconds and years outside the input range.
    - `metadata` object, required
      - `time_standard` 'UT1', required
      - `historical_accuracy_certified` unknown, required
      - `warnings` string[], required

## Other responses

- `400`: Invalid request, malformed JSON, out-of-range date/location, unknown model, invalid timezone or ambiguous/nonexistent clock-change time. Invalid attempts reaching quota reservation consume one unit.
- `401`: Missing, invalid, revoked API key or unavailable activated key owner. Dashboard cookies do not authenticate calculation routes.
- `403`: Origin not allowed by production CORS policy. Server-to-server requests can omit Origin.
- `429`: Monthly quota exhausted, per-user two-request concurrency reached, or nginx rate/connection admission refused. Retry-After: 2 is sent for application per-user concurrency only, not a promise that monthly quota resets in two seconds.
- `502`: Engine unavailable, unsuccessful internal server response or invalid upstream JSON. No engine internals are exposed.
- `503`: Four-request global calculation pool full (Retry-After: 2), maintenance or upstream service unavailable.
- `504`: Application engine timeout: 15 seconds normally; planetary events, house ingresses, aspect windows, event calendar, eclipse geometry, electional search, and event-rule search use 30 seconds; Nakshatra Timeline plus the explicitly enumerated readiness, robustness, location, uncertainty, and electional-audit family use 60 seconds. Timer includes response-body parsing; an admitted timeout consumes quota.

---

[API](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api.md) · [All operations](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/revisions/f041e924cea3?raw)