Astrocartography API: Turn Birth Charts Into Location-Based Astrology Experiences

What Exactly Is Astrocartography?

A natal chart normally represents planetary positions using houses, signs, aspects, and angles.

Astrocartography takes those same birth details and asks a geographical question:

“Where on Earth was each planet angular at the moment this person was born?”

For every planet, four primary angles can be projected across the globe:

The combination of Planet + Angle gives an astrology application the precise context needed to explain what a particular location could represent for a user.

A Map Becomes Much More Useful When Users Can Ask a Question

Showing dozens of planetary lines on a world map may look impressive, but most users aren't opening an astrology app because they want to study coordinate geometry. They have a specific question.

This turns Astrocartography from a complicated astrology technique into an intuitive search and discovery experience.

Example: Career Location Finder

Imagine a user opening an astrology application and selecting: Explore → Career.

Instead of receiving another paragraph of generic career advice, they see a world map highlighting locations connected with the planets and angles relevant to career—such as a Jupiter-MC line.

The map becomes an active feature rather than a static chart.

Example: Love Location Finder

The same experience can be built around relationships using category endpoints.

AstrologyAPI’s category endpoint returns only lines associated with a chosen life theme rather than requiring your app to filter and render every planetary line.

The Three Astrocartography APIs

AstrologyAPI provides three specialized Astrocartography endpoints tailored for different levels of product exploration.

How to Use the Three Astrocartography APIs

All three APIs accept standard birth parameters:

• Date of birth (day, month, year)
• Exact birth time (hour, min, optional second)
• Timezone offset (tzone)
• Birthplace latitude & longitude (lat, lon)

Example Implementation: Requesting Full Travel Map Data

Here is how an application backend can call the Travel API using standard JavaScript:

const ASTROLOGY_API_KEY = process.env.ASTROLOGY_API_KEY;

async function fetchAstrocartographyMap(userBirthData) {
  const response = await fetch('https://json.astrologyapi.com/v1/acg/travel', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'authorization': 'Basic ' + Buffer.from(ASTROLOGY_API_KEY).toString('base64'),
    },
    body: JSON.stringify({
      day: userBirthData.day,
      month: userBirthData.month,
      year: userBirthData.year,
      hour: userBirthData.hour,
      min: userBirthData.min,
      lat: userBirthData.lat,
      lon: userBirthData.lon,
      tzone: userBirthData.tzone,
      include_parans: true,
    }),
  });

  if (!response.ok) {
    throw new Error(`Astrocartography API error: ${response.statusText}`);
  }

  const data = await response.json();
  return data;
}

API 1: Travel — Build the Complete Astrocartography Map

The Travel API endpoint (POST /v1/acg/travel) calculates planetary positions and returns line paths across four angles (AC, DC, MC, IC).

AC and DC lines are returned as arrays of latitude and longitude coordinates that form curved paths over the map projection. MC and IC lines represent vertical meridians with fixed longitude values.

API 2: Category Based Location — Answer Specific User Questions

When users don't need the entire global map, request category endpoints such as /v1/acg/category-location/LOVE or /v1/acg/category-location/CAREER.

Supported categories include: Adventure, Career, Communication, Creativity, Health, Learning, Love, Money, Power, Relationship, Spirituality, Success, Transformation, Travel, Vitality, and Wealth.

API 3: Planetary Line Report — Single Line Focus

When a user taps an individual planetary line on your map (e.g. Venus Descendant), call POST /v1/acg/planetary-line/DC/VENUS to retrieve the exact line geometry and detailed thematic breakdown for that specific line.

How the Three APIs Work Together

The API Returns Coordinates. You Control the Experience.

AstrologyAPI provides pure, structured latitude and longitude coordinates. This gives your frontend engineering team full freedom to render the map using your preferred library:

• Mapbox GL JS / Mapbox Mobile SDKs
• Google Maps JavaScript API
• Leaflet.js
• D3.js SVG / Canvas Projection
• Custom native map engines

Go Beyond Planetary Lines with Parans

A paran occurs at a geographic latitude where two planetary lines cross or share angularity. These locations mark powerful intersections where two planetary energies combine.

Enabling include_parans: true in the Travel API returns these latitude crossings, allowing your platform to highlight high-potency "power spots" on the map.

What You Can Build with an Astrocartography API

Astrocartography Can Create a Natural Premium Feature

While basic birth charts and horoscopes are commonplace, Astrocartography offers a fresh interaction model: shifting from “Tell me about myself” to “Where should I go?”

This creates compelling monetization touchpoints:

• Premium relocation search tool behind a subscription tier
• Paid single-purchase Astrocartography PDF report
• Unlocked category filters (Love Zones, Money Hotspots)
• Unlimited city search & location comparisons

How AstrologyAPI Can Help You Build Astrocartography Faster

Building an Astrocartography engine in-house requires complex astronomical and geographic capabilities:

AstrologyAPI handles this calculation layer completely. Your backend receives clean, ready-to-plot coordinates so your team can focus on UI, brand, and monetization.

From Birth Details to a World Map: 5-Step Checklist

1. Collect Birth Data: Date, exact time, birthplace coordinates, and timezone.
2. Request API Endpoints: Send payload to Travel, Category, or Line endpoints.
3. Parse Coordinate Payload: Extract latitude/longitude arrays for lines and parans.
4. Plot on Map: Render curves and vertical meridians using Mapbox or Google Maps.
5. Overlay Interpretation: Present thematic insights for selected cities and lines.

The Next Astrology Question May Not Be “When?”

Astrology products have traditionally focused on timing questions: “When will I find success?” or “When should I start a business?”

Astrocartography introduces a transformative spatial question:

“WHERE?” — Where in the world should I build my career, find love, or create a home?

The birth chart stays constant. The experience around it becomes global.

Astrocartography content should be presented for self-reflection, educational, and personal exploration purposes. Applications should avoid framing location insights as financial, legal, or relocation guarantees.