Best places API

For every city in the pool the endpoint measures the distance to each line the chosen category names, and weights it by how close it falls. The distance is computed from the body's hour angle and altitude rather than against a drawn polyline, which makes it exact: the distance to a rising or setting line is the body's altitude in degrees of arc, because zenith distance is great-circle distance from the point the body stands over; and a meridian line's offset is the hour angle in degrees of longitude, so the ground distance is that times the cosine of latitude. Influence falls off linearly to nothing at the orb, 1126 km by default, which is the 700 miles Jim Lewis used. Supportive and challenging totals are kept apart and every contributing line comes back with its own distance, so a place can be strong and turbulent rather than averaged into the middle. Results are then thinned so no two are within 300 km of each other, and the number suppressed is reported.

curl -X POST https://api.astroway.info/v1/acg/best-places \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "date": "1990-05-15",
  "time": "14:30:00",
  "timezoneOffset": 3,
  "category": "career",
  "limit": 10
}'

{
  "ok": true,
  "data": {
    "type": "acg-best-places",
    "orbKm": 1126,
    "minSeparationKm": 300,
    "suppressedAsTooClose": 99,
    "maxPossibleSupportive": 12,
    "pool": { "citiesConsidered": 34028, "citiesWithAnyLine": 13589 },
    "places": [
      {
        "name": "Ålesund",
        "country": "Norway",
        "countryCode": "NO",
        "lat": 62.4723,
        "lon": 6.1549,
        "population": 46747,
        "supportive": 3.2529,
        "challenging": 0,
        "net": 3.2529,
        "supportivePercent": 27.1,
        "lines": [
          {
            "planetName": "Sun",
            "angle": "MC",
            "weight": 3,
            "polarity": "supportive",
            "distanceKm": 22,
            "contribution": 2.9414
          }
        ]
      }
    ],
    "attribution": {
      "source": "GeoNames",
      "licence": "CC BY 4.0",
      "licenceUrl": "https://creativecommons.org/licenses/by/4.0/"
    }
  }
}

Use it when a user has asked the obvious next question. Astrocartography draws the lines and a category filter says which ones matter for money or love; this says where to actually go. It is the difference between a map and an answer. In a product, feed the result straight into a shortlist: each place carries its coordinates, population, timezone, and the exact lines that put it there with distances in kilometres, so the reasoning can be shown rather than asserted. The birth place is not needed and is not used, because the lines belong to the birth moment.

The thinning is not cosmetic. An astrocartography line is a curve, so every settlement along it scores nearly the same, and without spreading the results the top ten for career came back as ten Norwegian towns inside 70 km, two of which were districts of the third. Set `minSeparationKm` to 0 to see the raw order. **This is not geocoding.** The city list is bundled and starts at 15,000 people: a smaller town is absent from the ranking rather than ranked poorly, and an arbitrary place name cannot be resolved. To score a specific point of your own, pass its coordinates to the astrocartography zones endpoint instead. City names, coordinates and populations come from the GeoNames geographical database, used under CC BY 4.0; displaying them carries the same credit, which is why the attribution ships in every response body rather than only here.