Timezones and historical offsets

A birth time is local civil time at the birthplace. To compute a chart, Navapatra turns it into a UTC instant using the time zone rules of the birthplace on that date, never your server’s zone or the user’s device zone. A wrong offset moves the lagna by about one degree for every four minutes, so this step matters more than any other.

How the offset is chosen

For every birth, in this order:

1. birth.utcOffset, if you send one (for example "+05:30"), is used as is. offsetSource is override.
2. Otherwise the zone is birth.tzid if you send one (for example "Asia/Kathmandu"), else the zone of the place you named in place.query, else a lookup from lat and lng.
3. The offset for that zone on that date comes from the IANA tz database, including every historical change. offsetSource is tzdb.

The one exception is options.nepalHistoricOffset: "historic_0540", described below, which reports offsetSource: "historic_0540".

The response’s subject shows the result, so you can always check what was applied:

"subject": {
  "instantUtc": "1993-08-28T08:50:00Z",
  "place": { "lat": 28.2096, "lng": 83.9856 },
  "tzid": "Asia/Kathmandu",
  "utcOffset": "+05:45",
  "offsetSource": "tzdb",
  "birth": { "ad": "1993-08-28", "bs": "2050-05-12" }
}

Before standard time was adopted, places kept local mean time, and the offset can include seconds. A 1905 birth in Kathmandu returns "utcOffset": "+05:41:16".

Zone lookup from coordinates

The coordinate lookup uses present-day zone boundaries and can be wrong within a few kilometres of a border. It also does not know about zones that have since been merged. If you know the zone, send birth.tzid; if you know the exact offset the birth was recorded in, send birth.utcOffset. Places resolved from place.query use the zone recorded for that place in the gazetteer.

Nepal before 1986

Nepal’s clocks ran at UTC+05:30 until the end of 1985 and have run at UTC+05:45 since 1 January 1986, 00:00 local time. The tz database records exactly this, and it is the default.

Some older Nepali software and records used UTC+05:40 for births before the switch instead. If your users’ existing charts were made that way and you need to match them, set options.nepalHistoricOffset to historic_0540. It only affects births in Asia/Kathmandu before 1986-01-01; later births and other zones are unchanged. The response reports utcOffset: "+05:40" with offsetSource: "historic_0540", so a stored chart always shows which convention it used.

The difference is visible. The same Kathmandu birth on 1980-05-15 at 10:30:

Setting	utcOffset	instantUtc	Lagna
default (tzdb)	+05:30	1980-05-15T05:00:00Z	Karka 106.96°, Ashlesha pada 1
historic_0540	+05:40	1980-05-15T04:50:00Z	Karka 104.82°, Pushya pada 4

Ten minutes of offset moved the lagna into a different nakshatra. Use sensitivityMinutes to see how close a chart sits to such a boundary.

Overrides

{
  "birth": {
    "calendar": "AD",
    "date": "1980-05-15",
    "time": "10:30",
    "place": { "lat": 27.7172, "lng": 85.324 },
    "utcOffset": "+05:30"
  }
}

• utcOffset is ±HH:mm, at most 14 hours. It wins over everything else and skips the ambiguity checks below.
• tzid must be a valid IANA zone name. It replaces the lookup but still uses the tz database for the offset.
• Both are echoed in subject, so a saved response shows how it was computed.

Ambiguous local times

Where clocks change for daylight saving time, some local times never happen (the clocks jump forward over them) and some happen twice (the clocks fall back). Navapatra will not guess. It returns 422 with code: "ambiguous_local_time", the kind of problem and both candidate instants:

{
  "type": "https://navapatra.com/docs/errors#ambiguous_local_time",
  "title": "Ambiguous local time",
  "status": 422,
  "detail": "local time is skipped or repeated in this zone",
  "code": "ambiguous_local_time",
  "requestId": "c3f18232-b4cb-4a64-ba5b-5946d0b00c17",
  "details": {
    "tzid": "America/New_York",
    "kind": "overlap",
    "candidates": ["2021-11-07T05:30:00Z", "2021-11-07T06:30:00Z"]
  }
}

That birth, 01:30 on 7 November 2021 in New York, happened twice. Ask the user (or your records) which one, then repeat the request with options.disambiguation:

• "earlier" picks the first candidate instant.
• "later" picks the second.

For a gap (kind: "gap", for example 02:30 on 14 March 2021 in New York, which never happened), the two candidates are the wall time read with the offset before and after the change; earlier and later choose between them the same way.

{
  "birth": {
    "calendar": "AD",
    "date": "2021-11-07",
    "time": "01:30",
    "place": { "lat": 40.7128, "lng": -74.006 }
  },
  "options": { "disambiguation": "later" }
}

The response then shows "instantUtc": "2021-11-07T06:30:00Z" and "utcOffset": "-05:00". Nepal has never used daylight saving time, so births in Nepal are never ambiguous.

Look up a zone

GET/v1/timezone1 creditReference

Returns the zone for a coordinate and its offset at an instant (now, if you leave instant out):

curl "https://api.navapatra.com/v1/timezone?lat=27.7172&lng=85.324&instant=1985-06-01T00:00:00Z" \
  -H "Authorization: Bearer $NAVAPATRA_API_KEY"

{ "tzid": "Asia/Kathmandu", "utcOffset": "+05:30", "instant": "1985-06-01T00:00:00Z", "source": "tz-lookup" }

Supported range

Birth dates from AD 1900-01-01 to 2100-12-31. Anything outside returns 422 out_of_range with the AD date in details.