---
title: "Best places for a life category"
method: POST
path: "/acg/best-places"
tags: ["Astro-Geography"]
---

# Best places for a life category

`POST /acg/best-places`

Rank cities against the astrocartography lines of a chart for one of the 19 life categories. Distance to a line is computed from the body hour angle and altitude rather than against a discretised polyline, so it is exact: the distance to a horizon line IS the altitude in degrees of arc, and a meridian line offset is the hour angle times cos(latitude). Supportive and challenging totals are returned separately with every contributing line and its distance, so a strong-but-turbulent city is distinguishable from an average one. Bundled GeoNames set of 34,028 places above 15,000 people. **Not geocoding**: a smaller town is absent from the ranking rather than ranked poorly, and an arbitrary place name cannot be resolved.

## Request body

- AcgBestPlaces — Birth data plus a life category. Birth coordinates are optional and unused for the ranking: astrocartography lines are a property of the birth moment, not of the birth place.
  - `date` string, required
  - `time` string, required
  - `timezoneOffset` number, nullable — Hours from UTC at the given moment, not minutes. Fractional zones are hours too: 5.5 for India, 5.75 for Nepal, -3.5 for Newfoundland. Defaults to 0, meaning UTC.
  - `latitude` number, required
  - `longitude` number, required
  - `houseSystem` string
  - `name` string
  - `city` string
  - `zodiacType` 'tropical' | 'sidereal'
  - `ayanamsaId` number, nullable
  - `ayanamsa` 'fagan-bradley' | 'lahiri' | 'de-luce' | 'raman' | 'krishnamurti' | 'kp' | 'yukteshwar' | 'jn-bhasin' | 'true-citra' | 'djwhal-khul' — Sidereal school by name. Lahiri when omitted. Equivalent to ayanamsaId; send either.
  - `cosmogram` boolean
  - `category` string, required — One of the 19 ACG life categories. The list is at GET /v1/acg/categories.
  - `countries` string[] — ISO 3166-1 alpha-2 codes to restrict the search to. Omit to search the whole bundled list.
  - `minPopulation` integer — Floor on city population. The bundled set starts at 15000, so a lower value changes nothing.
  - `orbKm` number — How far a line reaches, kilometres. Default 1126, which is the 700 miles Jim Lewis used.
  - `limit` integer — How many cities to return. Default 25.
  - `minSeparationKm` number, nullable — Keep returned cities at least this far apart, kilometres. Default 300. An ACG line is a curve, so without thinning the top of the ranking is the densest stretch of one line rather than a set of places. Set 0 to disable and see every city in score order.
  - `sort` 'net' | 'supportive' — `net` (default) ranks on supportive minus challenging. `supportive` ignores the challenging side when ordering, though it is still reported.

## Response `200`

Successful calculation

- object
  - `ok` boolean
  - `data` object
    - `type` string, nullable
    - `category` object, nullable
      - `id` string, nullable
      - `name` string, nullable
      - `lines` unknown[], nullable
        - unknown
    - `orbKm` number, nullable
    - `maxPossibleSupportive` number, nullable
    - `pool` object, nullable
      - `citiesConsidered` number, nullable
      - `citiesWithAnyLine` number, nullable
      - `minPopulation` number, nullable
    - `count` number, nullable
    - `places` object[], nullable
      - `name` string, nullable
      - `country` string, nullable
      - `countryCode` string, nullable
      - `lat` number, nullable
      - `lon` number, nullable
      - `population` number, nullable
      - `supportive` number, nullable
      - `challenging` number, nullable
      - `net` number, nullable
      - `supportivePercent` number, nullable
      - `lines` object[], nullable
        - `planetId` number, nullable
        - `planetName` string, nullable
        - `angle` string, nullable
        - `weight` number, nullable
        - `polarity` string, nullable
        - `distanceKm` number, nullable
        - `contribution` number, nullable
    - `dataset` object, nullable
      - `source` string, nullable
      - `licence` string, nullable
      - `note` string, nullable
    - `attribution` object, nullable
      - `source` string, nullable
      - `licence` string, nullable
      - `licenceUrl` string, nullable

## Other responses

- `400` — Validation error
- `401` — Missing or invalid API key

---

[API](https://skmtc.net/astroway/apis/astroway-calculation-api.md) · [All operations](https://skmtc.net/astroway/apis/astroway-calculation-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/astroway/astroway-calculation-api/revisions/6828e5609564/schema)