The birth object

Operations about a person take a birth object in the POST body. Birth data never goes in a URL.

• date string (date) required

  e.g. "1990-08-13"

• time string

  pattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$ · e.g. "06:30"

• time_accuracy string

  With "unknown", lagna- and house-dependent fields are omitted and listed in warnings — never filled with a noon default.

  one of exact, approximate, unknown · default "exact"

• place Coordinates or object or object required

  Coordinates, a place_id from /v1/places/search, or a free-text query. A vague query returns 422 place_ambiguous with candidates; the API never guesses.

  One of:

  1. Coordinates
     Fields

     • latitude number required

       ≥ -90 · ≤ 90

     • longitude number required

       ≥ -180 · ≤ 180

     No other fields are accepted.

  2. object
     Fields

     • place_id string required

     No other fields are accepted.

  3. object
     Fields

     • query string required

       at least 2 characters · at most 120 characters

     No other fields are accepted.

• timezone string

  "auto" (from coordinates AND date), an IANA name, or a fixed offset like "+05:30".

  default "auto"

No other fields are accepted.

Place

Send the place in one of three ways:

• Coordinates, the most precise: { "latitude": …, "longitude": … }.
• A place id from place search: { "place_id": "pl_…" }.
• A name: { "query": "Noida" }.
  • If nothing matches, the answer is 422 place_not_found.
  • If several places match, it is 422 place_ambiguous, with error.candidates to choose from.
  • The API never guesses.

Timezone

timezone defaults to "auto": the zone and UTC offset in force at that place on that date, including historical changes. You can also send an IANA name ("Asia/Kolkata") or a fixed offset ("+05:30"). The zone used comes back in meta.timezone_used.

Older dates in India. With "auto", India is +05:30 from 1906, and +06:30 from October 1941 to May 1942 and from September 1942 to October 1945. Before 1906 the timezone database has one zone for all of India, at +05:21, but cities kept their own local time then. For a birth before 1906, send a fixed offset if you know the time the clock was keeping.

Time accuracy

• exact (the default) and approximate compute everything.
• unknown omits the fields that depend on the lagna or the houses and lists them in warnings. It never fills them with a noon default.
• Operations that cannot work without a time answer 422 time_required.

Dates