Sonification
A birth chart is a system of ratios, and ratios are what an ear reads better than an eye. Fifteen aspects and their orbs is a table to work through; the same fifteen as a chord you hear as "tense" or "open" in two seconds. A tight square sounds different from a wide one without anyone having to interpret an orb column.
Kepler worked this out in Harmonices Mundi in 1619 and had no way to hear it. He had the numbers; we have the loudspeaker.
/api/sound/* renders a chart to audio. The mapping runs server-side, a dedicated service synthesises it, and what comes back is a sound file.
Required module
All sound endpoints require the sound:calc feature permission, granted by the module:sonification module. It is included in every plan and is not sold separately.
What this is, and what it is not
The method is parameter mapping sonification — mapping a data dimension onto an auditory one. It is a real research field: ICAD has been running since 1992, The Sonification Handbook (Hermann, Hunt & Neuhoff, 2011) is the standard reference, and the technique is what the pitch of a pulse oximeter, a Geiger counter and NASA's Chandra sonifications are all built on.
The method being scientific does not make astrology scientific, and nothing here claims it does. The distinction that matters:
| What is true | What we do not say |
|---|---|
| The data being sonified is astronomy: ecliptic longitudes from JPL ephemerides, and the angles between them. | That the sound demonstrates anything about character or events. |
| The rendering is reproducible and deterministic: the same moment always gives the same file. | That "science says" your chart sounds like this. |
Kepler is not decoration here either. The ratios in Harmonices Mundi were real angular velocities at perihelion and aphelion — correctly computed celestial mechanics. His mystical reading did not survive; the ratios did. That is exactly the line this feature draws.
No AI
No model, no prompt, no generation. The sound follows from the numbers, and the same chart always produces the same file. That is the feature, not a limitation: it is why the output can be trusted to mean what it claims.
How it is built
The chart is turned into a score by a documented, deterministic procedure and that score is synthesised on our servers. The axes it uses are the ones an astrologer already reads — orbital period, longitude, aspect and orb, element, house, dignity, retrograde motion — and each of them drives a property of the sound. The procedure itself is not published.
That is a deliberate trade. The sonification literature asks for a reproducible mapping, and this one is reproducible: identical input always yields an identical file, and you can verify that yourself. What it is not is open, because the mapping is the part of this that had to be invented.
Natal
curl -X POST "https://api.astroapi.cloud/api/sound/natal" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-o chart.mp3 \
-d '{
"dateTime": "1990-06-15T14:30",
"location": {
"latitude": 52.37,
"longitude": 4.89,
"timezone": "Europe/Amsterdam"
}
}'Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dateTime | string | Yes | YYYY-MM-DDTHH:mm, local clock time at location |
location | object | Yes | latitude, longitude and an IANA timezone |
houseSystem | string | No | Default placidus |
points | array | No | Celestial points to sound. Defaults to the ten bodies, both nodes and both Liliths |
profile | string | No | kepler (default) or aurora. See below |
length | string | No | full (default) or short |
duration | number | No | Length in seconds, 10–300. Overrides length |
skipSilence | boolean | No | Cut the passages where nothing sounds. Off by default; the piece then comes out shorter than the length you asked for |
format | string | No | mp3 (default) or wav |
The response body is the audio. A 45-second piece is about 700 kB as MP3 at 128 kbps, and about 8.6 MB as WAV.
Response headers
| Header | Meaning |
|---|---|
X-Sound-Mapping | The mapping version that produced these bytes |
X-Sound-Profile | The profile that produced them |
X-Sound-Cache | hit or miss |
Profiles
The same chart, rendered two ways. profile picks one; both take the same input and neither changes what the chart says.
| Profile | |
|---|---|
kepler | The default. Precise and austere. |
aurora | Warmer and easier on the ear, at the cost of being less precise about the exact degree. |
The response carries X-Sound-Profile, so you can always tell which one produced the bytes.
length is full (45 seconds, 120 for transits) or short (20 and 45). A short piece is the whole chart at a quicker pace, not a truncated one.
skipSilence is a different kind of shortening. A chart does not spread its points evenly — a stellium puts five of them side by side and leaves a quarter of the zodiac empty — and because the houses are the time axis, an empty stretch becomes a stretch where nothing happens. Turning it on cuts those. It is off by default because the even pace is itself information: a quiet quarter is a real feature of the chart. It applies to natal pieces only; in a transit piece the time axis is the period, so a position in the piece is a date and cutting would make the timeline lie.
A player: the timeline endpoint
An <audio> element cannot send an API key header, and a player that highlights a wheel needs to know when each point sounds. Both are solved by one call:
curl -X POST "https://api.astroapi.cloud/api/sound/natal/timeline" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"dateTime": "1990-06-15T14:30",
"location": { "latitude": 52.37, "longitude": 4.89, "timezone": "Europe/Amsterdam" }
}'{
"data": {
"type": "sound-timeline",
"attributes": {
"audioUrl": "https://api.astroapi.cloud/api/sound/natal?dateTime=...&expires=...&sig=...",
"format": "mp3",
"duration": 45,
"mappingVersion": 1,
"markers": [
{
"pointId": "sun",
"onset": 12.4,
"duration": 9.8,
"longitude": 84.23,
"aspects": [
{ "partnerId": "venus", "aspect": "trine", "onset": 12.5 }
]
}
]
}
}
}audioUrl is signed with an HMAC over its path and query. Put it straight into <audio src>: fetching it needs no headers and costs nothing against your allowance. This is one counted request, not two.
The URL is stable within the hour it was minted in — ask for the same chart twice in that hour and you get a byte-identical URL, which is what lets it be cached rather than re-rendered per listener. It stays valid for at least an hour and at most two.
The markers carry the time axis and each point's longitude — enough to light up a wheel in step with the audio. They deliberately carry no frequencies, levels, timbres, ratios or orbs.
Transits
A period rather than a moment. The natal chart is a chord held underneath; every contact a transiting body makes enters wide, closes to a pure interval on the day it is exact, and opens again. A year becomes a couple of minutes in which the tension arc of the year is the tension arc of the piece.
curl -X POST "https://api.astroapi.cloud/api/sound/transit" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-o year.mp3 \
-d '{
"birthDate": "1990-06-15T14:30",
"birthLocation": { "latitude": 52.37, "longitude": 4.89, "timezone": "Europe/Amsterdam" },
"transitDateStart": "2027-01-01T00:00",
"transitDateEnd": "2027-12-31T00:00",
"transitLocation": { "latitude": 52.37, "longitude": 4.89, "timezone": "Europe/Amsterdam" },
"duration": 120
}'The period may span at most two years, the same limit as /api/calc/transit. It is one calculation and one render regardless of how long the period is — one counted request, not one per day.
Quota and limits
- One render is one counted request, natal or transit.
- A piece is capped at 300 seconds, so nobody buys an hour of CPU for the price of one call.
- The audio is streamed as it is encoded, so playback starts well before the piece is finished — a 45-second piece encodes at roughly 28× realtime.
- Identical input produces identical output. Repeated fetches of the same signed URL are served from cache and answer with
X-Sound-Cache: hit; the response also carries a one-hourCache-Control, so your own client or CDN can hold on to it.
The sound is not an API contract
If version two of the mapping is better, what an existing call returns will change. That is unavoidable with audio, and desirable.
X-Sound-Mapping carries the version that produced the bytes, so a client that notices a difference can see why.
Formats
| Format | Size (45 s stereo) | Notes |
|---|---|---|
mp3 | ~700 kB at 128 kbps | Default. Plays everywhere, including every Safari |
wav | ~8.6 MB | Lossless, for editing or archiving |
Opus would be smaller again and is the technically better codec, but every Opus encoder is a WebAssembly build of libopus and Safari is the weak point on exactly the platform this gets shared on. format already exists in the request, so adding it later is an encoder, not a redesign.
What you cannot get
The score — the intermediate representation the synthesiser reads — is not served. Anyone holding a score next to its input can read the mapping straight off it. The endpoints return audio, and the player payload carries the time axis and nothing else.