# Birth chart API

Calculate a birth chart over HTTP from a local birth time and place, with skipped and repeated clock times, local mean time and the zone history stated rather than guessed.

Engine 1.0.0: On npm.
Archive identity and release status: https://zodiacs.org/developers/engine/

## A chart from a local birth time

POST /api/v1/chart takes a local date and time with an IANA time zone, or a UTC instant, with a latitude, an east longitude and a house system. It answers with the Sun, the Moon, the planets and the lunar nodes, the angles, the house cusps and the major aspects, and the UTC instant it used.

The birth details here are synthetic, from the API's documented example; the guide checks run this code against the committed answer.

~~~javascript
const response = await fetch('https://zodiacs.org/api/v1/chart', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    local: { date: '1990-06-15', time: '14:30', zone: 'Europe/Paris' },
    latitude: 48.8566,
    longitude: 2.3522,
    houseSystem: 'whole',
  }),
});
const answer = await response.json();
if (!response.ok) throw new Error(`The service refused this request: ${response.status} ${answer.error?.code}`);
const { instant, local, bodies, angles } = answer.result;
console.log(instant, local.offsetMinutes, local.flags);
for (const { body, sign, degree } of bodies) console.log(body, sign, degree.toFixed(2));
console.log('Ascendant', angles.asc.toFixed(2));
~~~

## How the time was read

For a local time the answer says how it was read: its offset from UTC, flags for a clock time that was skipped (dst-gap) or repeated (dst-fold) or read on local mean time (lmt), and which zone history answered. Before 1970 that history is tzdb 2025c with its backzone file; from 1970 it is the server runtime's own time zone data.

The endpoint needs a time; it has no form for an unknown birth time. Without one, do not send noon as if it were known: ask for positions on the date, show the rising sign and the houses as unknown, and say that the Moon can change sign during the day.

## Hosted or on your machine

The same engine runs in Node, Deno, Bun, browsers and Workers as @zodiacs/engine: natalChart for the chart and @zodiacs/engine/geo for local times. Use it when birth details should not leave the device, and the API when a server call is simpler.

Its thirteen house systems are each defined as Swiss Ephemeris defines them, and given the same sidereal time, latitude and obliquity, each agrees with Swiss Ephemeris's house function to within 0.0001″, and Placidus, which iterates, to 0.01″.

## References

- [Compute API: chart](https://zodiacs.org/developers/compute/#chart)
- [Natal chart recipe](https://zodiacs.org/developers/docs/natal/)
- [Calculation conventions](https://zodiacs.org/developers/docs/conventions/)