/api/v2/western/chart-similarity/famous-peopleCompare one Western natal chart against the precomputed famous-person chart index and return ranked matches with scores, shared placement counts, shared aspect counts, optional angle comparisons, and plain-English reasons for each match.
Full URL: https://api.freeastroapi.com/api/v2/western/chart-similarity/famous-people
Index size: about 15,000 famous-person chart signatures. The current index contains 15,739 charts.
Authentication: send x-api-key.
The endpoint compares signs, close degree positions, shared natal aspect patterns, and angles when both charts have usable time and location data. Results are ranked by an overall score and include component scores so you can show users why the match appeared.
Personal planets, social planets, and generational planets are separated in the breakdown. This helps avoid same-generation outer-planet matches dominating over more user-visible Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, and aspect similarities.
When a famous-person row cannot use angles, breakdown.angle_score is omitted and confidence.houses_and_angles_used is false. Placement and aspect matching still run.
year, month, day, hour, minute, city, lat, lng, and tz_str.curl -X POST "https://api.freeastroapi.com/api/v2/western/chart-similarity/famous-people" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"natal": {
"name": "Sample User",
"year": 1995,
"month": 9,
"day": 5,
"hour": 20,
"minute": 0,
"city": "Paris, France",
"lat": 48.8566,
"lng": 2.3522,
"tz_str": "Europe/Paris",
"true_node": true
},
"settings": {
"top_n": 10,
"include_angles": true,
"close_position_orb_deg": 5,
"close_angle_orb_deg": 5,
"close_aspect_orb_deg": 2,
"max_detail_items": 5
}
}'This example is trimmed from a real response for the 5 September 1995, 8:00 PM Paris test chart. Detail arrays are shortened so the docs stay readable, but the fields and values shown come from the actual endpoint shape.
{
"meta": {
"dataset": "famous_people_2026-07-09",
"dataset_version": "2026-07-09",
"dataset_size": 15739,
"rules_version": "western_chart_similarity_v1",
"zodiac": "tropical",
"house_system": "placidus"
},
"run": {
"settings": {
"top_n": 2,
"aspect_set": "major",
"include_angles": true,
"close_position_orb_deg": 5,
"close_angle_orb_deg": 5,
"close_aspect_orb_deg": 2,
"max_detail_items": 3
},
"compared_count": 15739,
"skipped_count": 0
},
"matches": [
{
"person": {
"id": "d52f63134396b2cb",
"name": "Carin Hjulstrom",
"gender": "Female",
"birth_time": "10:34 31/08/1963 +01:00",
"location": "Gothenburg Metropolitan Area, Sweden"
},
"score": 28,
"summary": {
"headline": "Strong personal planet and aspect match",
"match_strength": "light",
"explanation": [
"Personal planet matches: Moon, Sun, and Mercury.",
"Personal-planet aspects include Mars square Moon, Sun conjunct Venus."
],
"why_this_match": [
"You share close personal planet placements: Moon.",
"You share tight personal-planet aspect patterns: Mars square Moon."
],
"personal_planet_matches": [
"moon",
"sun",
"mercury"
],
"shared_aspects": [
"Mars square Moon",
"Sun conjunct Venus"
]
},
"breakdown": {
"placement_score": 41,
"aspect_score": 14,
"personal_placement_score": 48,
"social_placement_score": 0,
"generational_placement_score": 0,
"personal_aspect_score": 16,
"social_aspect_score": 0,
"generational_aspect_score": 0,
"placement_weight": 0.5,
"aspect_weight": 0.5,
"angle_weight": 0
},
"counts": {
"compared_positions": 11,
"same_sign_positions": 5,
"close_positions": 1,
"shared_major_aspects": 2,
"shared_close_aspects": 1
},
"confidence": {
"birth_time": "known",
"location_resolved": false,
"houses_and_angles_used": false
}
}
]
}Use summary.headline and summary.why_this_match for a user-facing ranked list. These fields are designed to explain the result without exposing every raw aspect row.
Use summary.personal_planet_matches, summary.social_planet_matches, and summary.generational_matches when you want to visually separate personal similarity from outer-planet generation overlap.
Use shared_positions, shared_aspects, and shared_angles for drill-down screens. The counts are enough for a compact card, while the detail arrays support an expanded view.
503 chart_similarity_dataset_missing means the famous-person similarity index is not available in the API runtime.
The current dataset is famous_people_2026-07-09 with 15,739 precomputed signatures. The response metadata includes the dataset version and size used for each run.
Scores are best used for ranking inside a single response. Treat the explanation fields and personal/social/generational breakdown as the user-facing story, not just the raw number.