FreeAstroAPIAstrocartography APILines, Relocation & City Ranking
Build destination search, relocation scoring, and world-map astrology products with dense WGS84 GeoJSON lines, curved geodesic-style ASC and DSC paths, MC and IC meridian geometry, paran crossings, and relocated chart summaries.
Built for map products and relocation workflows
The astrocartography surface is split into clear building blocks so teams can render maps, rank cities, score one destination, or generate relocated chart summaries without stitching together multiple custom pipelines.
Map-Ready Lines
Return dense WGS84 GeoJSON so frontend teams can draw MC, IC, ASC, and DSC overlays directly on 2D maps with no path rebuilding step.
Paran Hotspots
Surface paran combinations with focus-aware metadata and GeoJSON band geometry for advanced astrocartography explorers and hotspot UI.
City Scoring
Score one known destination across five public focus areas and explain where the score came from.
Ranked Destinations
Search and rank cities for career, romance, home, health, or spiritual focus without building your own ranking engine.
Endpoints
Start with one overview endpoint or combine the surface area for richer relocation and mapping experiences.
City Check
/api/v1/western/astrocartography/city-checkScore one city across career, romance, home, health, and spiritual focus areas in a single request.
Recommendations
/api/v1/western/astrocartography/recommendationsRank candidate cities for a chosen focus so users can explore the best destinations before committing to one.
Lines
/api/v1/western/astrocartography/linesReturn dense WGS84 GeoJSON line geometry for direct 2D map rendering, full-chart overlays, and map products without client-side path reconstruction.
Parans
/api/v1/western/astrocartography/paransExpose paran crossings and strongest focus themes for hotspot analysis, advanced map layers, and location intelligence.
Relocation
/api/v1/western/astrocartography/relocationGenerate a relocated chart plus a relocation summary tuned for move evaluation and destination comparison UX.
Start with one chart, then draw everything
The lines endpoint is the fastest starting point for map products. It returns dense WGS84 GeoJSON geometry that can be rendered directly, including curved ASC and DSC paths, vertical MC and IC tracks, and GeoJSON point crossings when requested.
One geometry contract for every line
MC, IC, ASC, and DSC all arrive as GeoJSON, so one renderer can draw the full chart.
Curved geodesic-style paths included
ASC and DSC are shipped as ready-to-draw coordinate sequences instead of reconstruction hints.
Crossings stay map-native
When enabled, crossings are returned as GeoJSON points that drop directly into your map layers.
{
"meta": {
"geometry_format": "geojson",
"coordinate_reference_system": "WGS84",
"coordinate_order": "longitude_latitude",
"line_sample_step_degrees": 0.25,
"crossing_count": 2
},
"lines": [
{
"id": "sun:asc",
"body": "sun",
"angle": "asc",
"geometry": {
"type": "LineString",
"coordinates": [
[-159.2, -68.0],
[-124.8, -48.0],
[-101.5, -32.0],
[-72.6, 0.0],
[-43.4, 32.0],
[15.4, 68.0]
]
}
},
{
"id": "venus:asc",
"body": "venus",
"angle": "asc",
"geometry": {
"type": "MultiLineString",
"coordinates": [
[[121.4, -62.0], [171.5, -20.0]],
[[-178.4, -8.0], [-123.4, 54.0]]
]
}
}
],
"crossings": [
{
"id": "sun:mc|moon:dsc",
"geometry": {
"type": "Point",
"coordinates": [-22.7, 0.0]
}
}
],
"notes": {
"rendering": "The payload is already dense enough for direct MapLibre or Mapbox drawing."
}
}Render astrocartography as a chart, not a slippy map
This mode uses a rectangular chart renderer with a fixed world frame, graticule, frame labels, and direct line plotting. It is designed to feel closer to classic astrocartography software while still drawing the same API geometry.
Classic Chart Demo
Rectangular chart view drawn from the astrocartography lines payload.
Chart-first Rendering
This view uses a fixed rectangular world chart instead of a slippy map. That gets much closer to classic astrocartography software because the geometry is rendered as a chart, not as an interactive map tile overlay. When the API returns `chart_families`, the renderer uses them as uninterrupted AC/DC guide curves underneath the exact branch lines.
Projection: plate carrée / equirectangular
Geometry: geojson, WGS84
Show the recommended city and the lines that justify it
A useful recommendations contract does more than rank cities. It also returns the destination coordinates, a city-scoped explanation block, and the exact line ids the renderer should draw for that city.
Recommendation Map Example
A ranked city list, its coordinates, and the exact lines referenced by the selected city’s map_line_ids.
How the client uses the payload
Read the ranked city coordinates from the recommendations response, then resolve the selected city’s map_line_ids against map.lines to draw only the relevant overlays.
Why Amiens ranked highly
Mercury MC is the strongest supportive line for this career search, with 3 nearby contributing line(s). The frontend switches the visible map overlays directly from that city’s map_line_ids instead of guessing which global lines matter.
Top Recommended Cities
Career FocusExample Recommendations Response
This example shows a real ranked city list and lets the viewer switch the active city from the same `results` array. The frontend uses the selected city’s `map_line_ids` to resolve the visible lines without reconstructing geometry.
{
"results": [
{
"city": {
"name": "Amiens",
"country": "FR",
"state": "Hauts-de-France",
"lat": 49.9,
"lng": 2.3,
"timezone": "Europe/Paris",
"population": 143086
},
"city_visual_explanation": {
"explanation_mode": "line_plus_paran",
"map_line_ids": [
"mercury:mc",
"neptune:mc",
"sun:mc",
"mars:dsc",
"true_node:mc",
"venus:asc",
"pluto:mc"
],
"primary_lines": [
{
"body": "mercury",
"angle": "mc",
"distance_km": 9,
"line_id": "mercury:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
},
{
"body": "neptune",
"angle": "mc",
"distance_km": 116.8,
"line_id": "neptune:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
}
],
"primary_parans": [
{
"id": "mars:dsc:true_node:mc:49.281",
"body_a": "mars",
"event_a": "dsc",
"body_b": "true_node",
"event_b": "mc",
"distance_km": 68.9,
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
}
]
},
"match_tier": "strong",
"rank": 1,
"score": 120.62,
"signal_strength": "strong",
"summary": "Mercury MC is the strongest supportive line for this career search, with 3 nearby contributing line(s)."
},
{
"city": {
"name": "Albert",
"country": "FR",
"state": "Hauts-de-France",
"lat": 50.00091,
"lng": 2.65096,
"timezone": "Europe/Paris",
"population": 10588
},
"city_visual_explanation": {
"explanation_mode": "line_plus_paran",
"map_line_ids": [
"mercury:mc",
"neptune:mc",
"sun:mc",
"mars:dsc",
"true_node:mc",
"venus:asc",
"pluto:mc"
],
"primary_lines": [
{
"body": "mercury",
"angle": "mc",
"distance_km": 16.1,
"line_id": "mercury:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
},
{
"body": "neptune",
"angle": "mc",
"distance_km": 91.5,
"line_id": "neptune:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
}
],
"primary_parans": [
{
"id": "mars:dsc:true_node:mc:49.281",
"body_a": "mars",
"event_a": "dsc",
"body_b": "true_node",
"event_b": "mc",
"distance_km": 80.1,
"is_close": false,
"visual_strength": "medium",
"source_focuses": [
"career"
]
}
]
},
"match_tier": "strong",
"rank": 2,
"score": 120.47,
"signal_strength": "strong",
"summary": "Mercury MC is the strongest supportive line for this career search, with 3 nearby contributing line(s)."
},
{
"city": {
"name": "Isbergues",
"country": "FR",
"state": "Hauts-de-France",
"lat": 50.62328,
"lng": 2.45902,
"timezone": "Europe/Paris",
"population": 10067
},
"city_visual_explanation": {
"explanation_mode": "line_plus_paran",
"map_line_ids": [
"mercury:mc",
"neptune:mc",
"sun:mc",
"mars:dsc",
"true_node:mc",
"venus:asc",
"pluto:mc"
],
"primary_lines": [
{
"body": "mercury",
"angle": "mc",
"distance_km": 2.4,
"line_id": "mercury:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
},
{
"body": "neptune",
"angle": "mc",
"distance_km": 103.8,
"line_id": "neptune:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
}
],
"primary_parans": [
{
"id": "mars:dsc:true_node:mc:49.281",
"body_a": "mars",
"event_a": "dsc",
"body_b": "true_node",
"event_b": "mc",
"distance_km": 149.4,
"is_close": false,
"visual_strength": "medium",
"source_focuses": [
"career"
]
}
]
},
"match_tier": "strong",
"rank": 3,
"score": 119.1,
"signal_strength": "strong",
"summary": "Mercury MC is the strongest supportive line for this career search, with 3 nearby contributing line(s)."
},
{
"city": {
"name": "Coudekerque-Branche",
"country": "FR",
"state": "Hauts-de-France",
"lat": 51.02288,
"lng": 2.39359,
"timezone": "Europe/Paris",
"population": 25201
},
"city_visual_explanation": {
"explanation_mode": "line_plus_paran",
"map_line_ids": [
"mercury:mc",
"neptune:mc",
"sun:mc",
"mars:dsc",
"true_node:mc"
],
"primary_lines": [
{
"body": "mercury",
"angle": "mc",
"distance_km": 2.2,
"line_id": "mercury:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
},
{
"body": "neptune",
"angle": "mc",
"distance_km": 107.5,
"line_id": "neptune:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
}
],
"primary_parans": [
{
"id": "mars:dsc:true_node:mc:49.281",
"body_a": "mars",
"event_a": "dsc",
"body_b": "true_node",
"event_b": "mc",
"distance_km": 193.9,
"is_close": false,
"visual_strength": "medium",
"source_focuses": [
"career"
]
}
]
},
"match_tier": "strong",
"rank": 4,
"score": 118.88,
"signal_strength": "strong",
"summary": "Mercury MC is the strongest supportive line for this career search, with 3 nearby contributing line(s)."
},
{
"city": {
"name": "Lillers",
"country": "FR",
"state": "Hauts-de-France",
"lat": 50.56345,
"lng": 2.48042,
"timezone": "Europe/Paris",
"population": 10104
},
"city_visual_explanation": {
"explanation_mode": "line_plus_paran",
"map_line_ids": [
"mercury:mc",
"neptune:mc",
"sun:mc",
"mars:dsc",
"true_node:mc",
"venus:asc",
"pluto:mc"
],
"primary_lines": [
{
"body": "mercury",
"angle": "mc",
"distance_km": 3.9,
"line_id": "mercury:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
},
{
"body": "neptune",
"angle": "mc",
"distance_km": 102.4,
"line_id": "neptune:mc",
"is_close": true,
"visual_strength": "high",
"source_focuses": [
"career"
]
}
],
"primary_parans": [
{
"id": "mars:dsc:true_node:mc:49.281",
"body_a": "mars",
"event_a": "dsc",
"body_b": "true_node",
"event_b": "mc",
"distance_km": 142.8,
"is_close": false,
"visual_strength": "medium",
"source_focuses": [
"career"
]
}
]
},
"match_tier": "strong",
"rank": 5,
"score": 118.82,
"signal_strength": "strong",
"summary": "Mercury MC is the strongest supportive line for this career search, with 3 nearby contributing line(s)."
}
],
"map": {
"chart_families": [
{
"body": "mars",
"id": "mars:horizon",
"kind": "horizon_cycle",
"member_line_ids": [
"mars:asc",
"mars:dsc"
]
},
{
"body": "venus",
"id": "venus:horizon",
"kind": "horizon_cycle",
"member_line_ids": [
"venus:asc",
"venus:dsc"
]
}
],
"lines": [
{
"angle": "mc",
"body": "mercury",
"id": "mercury:mc"
},
{
"angle": "mc",
"body": "neptune",
"id": "neptune:mc"
},
{
"angle": "mc",
"body": "sun",
"id": "sun:mc"
},
{
"angle": "dsc",
"body": "mars",
"chart_family_id": "mars:horizon",
"id": "mars:dsc"
},
{
"angle": "mc",
"body": "true_node",
"id": "true_node:mc"
},
{
"angle": "asc",
"body": "venus",
"chart_family_id": "venus:horizon",
"id": "venus:asc"
},
{
"angle": "mc",
"body": "pluto",
"id": "pluto:mc"
}
]
}
}Selected City Explanation
mercury MC
high9.0 km from the city marker. Focus: career.
neptune MC
high116.8 km from the city marker. Focus: career.
Paran: mars DSC / true_node MC
68.9 km from the city. This stays in the explanation block so the map can mention the supporting hotspot without scanning a global inventory.
Paran: venus ASC / pluto MC
112.3 km from the city. This stays in the explanation block so the map can mention the supporting hotspot without scanning a global inventory.
Render a full astrocartography chart in MapLibre
This embedded example renders the astrocartography lines contract directly in MapLibre using the same WGS84 GeoJSON geometry the API returns to clients.
MapLibre Demo
Astrocartography lines payload rendered directly on a world map.
Why this matters
The lines endpoint returns dense geodesic-style, map-ready WGS84 GeoJSON. ASC and DSC arrive as curved coordinate sequences, MC and IC arrive in the same geometry contract, and crossings are GeoJSON points when requested. When available, `chart_families` expose uninterrupted AC/DC horizon cycles so chart renderers can keep the curves continuous without reconstructing paths client-side.
Geometry: geojson, WGS84
MapLibre Source Snippet
import maplibregl from "maplibre-gl";
const horizonFamilies = (linesResponse.chart_families ?? []).map((family) => ({
type: "Feature",
properties: {
id: family.id,
body: family.body,
stroke: "#cbd5e1",
},
geometry: family.geometry,
}));
const lineFeatures = linesResponse.lines.map((line) => ({
type: "Feature",
properties: {
id: line.id,
body: line.body,
angle: line.angle,
stroke:
line.angle === "mc" ? "#fbbf24" :
line.angle === "ic" ? "#34d399" :
line.angle === "asc" ? "#38bdf8" :
"#fb7185",
},
geometry: line.geometry,
}));
map.on("load", () => {
map.addSource("astro-horizon-families", {
type: "geojson",
data: {
type: "FeatureCollection",
features: horizonFamilies,
},
});
map.addLayer({
id: "astro-horizon-families",
type: "line",
source: "astro-horizon-families",
paint: {
"line-color": ["get", "stroke"],
"line-width": 1.8,
"line-opacity": 0.52,
},
});
map.addSource("astro-lines", {
type: "geojson",
data: {
type: "FeatureCollection",
features: lineFeatures,
},
});
map.addLayer({
id: "astro-lines",
type: "line",
source: "astro-lines",
paint: {
"line-color": ["get", "stroke"],
"line-width": 2.5,
"line-opacity": 0.9,
},
});
});Astrocartography API FAQ
Do astrocartography endpoints require an accurate birth time?
Yes. The public astrocartography endpoints are timed calculations. Accurate birth time is required because angles, angular lines, and relocation chart outputs depend on the exact local birth instant.
What is the difference between lines, parans, and relocation?
Lines return angular world-map geometry, parans return crossing-style planetary event hotspots, and relocation returns the full relocated chart plus a summary for one destination city. They solve related but distinct product needs.
When should I use city-check instead of recommendations?
Use city-check when the destination is already known and you want a detailed multi-focus breakdown. Use recommendations when you want the API to rank cities for a chosen focus across a search scope.
Are the returned lines geodesic and ready for map rendering?
Yes. The lines payload returns dense, map-ready WGS84 GeoJSON geometry that can be drawn directly in tools like MapLibre. ASC and DSC are delivered as curved coordinate sequences, MC and IC use the same geometry contract, and the client does not need to reconstruct the path.
Ship relocation and location products faster
Get your API key, start with city scoring, and expand into maps, rankings, and relocated chart experiences as your product grows.
No credit card required for free tier.