Mayan Astrology API: Tzolkin Day Signs and Long Count

Feed one birth date to four Mayan zodiac sign calculators and you can get four different day signs back, with no explanation offered anywhere on the page. That is not sloppy code. It is an unstated choice about a single number, the one that ties an ancient day count to a civil calendar, and a tool that never names the number it used cannot be checked against anything at all.

The Mayan Astrology API makes that number a typed request field with a named default and returns the resolved value on every response. This post walks the arithmetic behind a day sign, shows four published constants returning four different answers for the same date, and hands you the calls that build a Tzolkin day sign calculator.

How is a Mayan day sign computed from a birth date?

A Mayan day sign is an integer function of the date rather than an astronomical lookup. Convert the date to a day number, subtract the correlation constant to get the days elapsed since the start of the Long Count, then read the coefficient off that count modulo 13 and the sign off the same count modulo 20. There is no ephemeris in the path, and no birth time or birthplace in the input.

Under the default constant the count starts on 11 August 3114 BCE in the proleptic Gregorian calendar, and that first day is itself 4 Ajaw 8 Kumkʼu. Take 15 June 1990. Its day number is 2,448,058, so 2,448,058 minus 584,283 leaves 1,863,775 elapsed days. That count modulo 13 is 4, and the start day carries the coefficient 4, so the coefficient is 8. The same count modulo 20 is 15, and the start day is Ajaw, the twentieth sign, so fifteen steps on lands on the fifteenth sign, Men. The day is 8 Men, and you can reproduce every step of that with a calculator.

That is the whole response for the date above, trimmed to the fields that carry the answer:

{
  "date": "1990-06-15",
  "daySign": "men",
  "daySignName": "Men",
  "daySignClassic": "Men",
  "daySignKiche": "TZʼIKIN",
  "number": 8,
  "trecena": { "number": 20, "dayOfTrecena": 8, "rulingSign": "lamat", "rulingSignName": "Lamat" },
  "reading": {
    "keynote": "The nawal Men, called TZʼIKIN in the highland daykeeping tradition, is the eagle, the long view taken from far enough up to see the whole valley. The sign itself is read as eagle.",
    "numberBand": "indifferent",
    "guidance": "Come down for one detail. A view that never lands is scenery, not knowledge."
  },
  "conventions": { "correlation": "gmt-584283" }
}

Ready to build this? The Mayan Astrology API gives you the day sign, the trecena and a composed reading from one date, on the same flat subscription as every other domain. See pricing.

Why do two Mayan day sign calculators disagree about one date?

Because they anchor the same count to different days. The correlation constant is the day number assigned to the first day of the Long Count, several are published, and shifting it by one day shifts every day sign in the calendar with it. The four constants this API accepts span five days end to end, which is more than enough to hand a reader four different signs for one birth date.

Here is that spread, captured live for 15 June 1990. Only the request field changed between calls:

Use the default unless you have a reason not to. It is the commonly accepted Goodman Martinez Thompson constant, the one the major institutional converter runs on, and the one that high precision radiocarbon dating of a dated Tikal lintel supported in 2013, published in Scientific Reports. The other three are accepted because published inscription readings sometimes use them and a researcher has to reproduce a printed value.

There is a second cause, and it is not a correlation at all. Some popular calculators do not run the classical count: the modern Dreamspell or 13 Moon system gives 29 February no place in its 260 day cycle, so its count and the classical one separate by another day at every leap year and disagree by a different amount at every date. RoxyAPI runs the classical, academically attested day count only, and every response says which constant produced it.

Why can a date before 1582 be off by ten days?

Because two civil calendars are in play and most tools never say which one they took. Dates here are read as proleptic Gregorian throughout, including below the Gregorian reform of 15 October 1582. A converter that switches to the Julian calendar under the reform disagrees with this API by ten or eleven days on the same typed input, and feeding it the Julian equivalent makes the two agree exactly.

The historical record makes that checkable rather than theoretical. Tenochtitlan fell on 13 August 1521 in the Julian calendar the Spanish were keeping, and the colonial chronicles record the day of the surrender as 1 Snake in the 260 day count. Typing 1521-08-13 into this API returns 4 Cuāuhtli, which looks wrong until you convert the date: 13 August 1521 Julian is 23 August 1521 proleptic Gregorian, and that date returns 1 Cōātl, snake, on the coefficient 1. The API is right, the input convention was not.

Rather than hide that, the Long Count converter flags it. Sending an inscription date back the other way returns the civil date, the day count, the day number, the Calendar Round and a plain note:

{
  "date": "0683-08-29",
  "longCount": "9.12.11.5.18",
  "daysSinceEpoch": 1386478,
  "julianDayNumber": 1970761,
  "calendarRound": "6 Etzʼnabʼ 11 Yax",
  "lordOfNight": "G1",
  "note": "This date precedes the Gregorian reform of 1582-10-15. Dates are read as proleptic Gregorian throughout, so a converter that switches to the Julian calendar below the reform will disagree by ten or eleven days on the same input.",
  "conventions": { "correlation": "gmt-584283" }
}

How do you call the Mayan astrology API for a day sign or a Long Count?

Every endpoint in this domain takes a date and nothing else. No birth time, no latitude, no longitude, no timezone, so there is no city lookup step in front of it and no coordinate handling to get wrong. That makes it the lightest input in the catalog, and it is why a date five millennia back costs exactly what today costs.

POST /mesoamerican-astrology/mayan/tzolkin is the day sign call, and POST /mesoamerican-astrology/mayan/long-count/convert runs in both directions.

curl -X POST https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/tzolkin \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15"}'
# => daySignName "Men", daySignKiche "TZʼIKIN", number 8,
#    trecena.number 20, conventions.correlation "gmt-584283"

import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data: day } = await roxy.mesoamericanAstrology.calculateTzolkin({
  body: { date: '1990-06-15' },
});

console.log(day.daySign);                 // "men"      <- canonical id, never translated
console.log(day.daySignName);             // "Men"      <- render this one
console.log(day.daySignKiche);            // "TZʼIKIN"  <- highland daykeeping name
console.log(day.number);                  // 8
console.log(day.conventions.correlation); // "gmt-584283"

import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

day = roxy.mesoamerican_astrology.calculate_tzolkin(date='1990-06-15')
print(day['daySignName'], day['number'], day['daySignKiche'])
print(day['reading']['guidance'])

claude mcp add-json --scope user roxy-mesoamerican \
  '{"type":"http","url":"https://roxyapi.com/mcp/mesoamerican-astrology","headers":{"X-API-Key":"YOUR_KEY"}}'

The converter takes exactly one of date or longCount. Sending both, or neither, returns a 400 that names the rule rather than guessing which direction you meant: Supply exactly one of date or longCount.

What does a full nawal chart return in one call?

POST /mesoamerican-astrology/mayan/chart is the whole day rather than a fragment of it. One request returns the Tzolkin block above, the Haab date, the five position Long Count with its elapsed day count and day number, the Calendar Round, the Lord of the Night, the Year Bearer, the five point Cruz Maya and a one paragraph summary. For 15 June 1990 that is 8 Men 8 Sotzʼ, Long Count 12.18.17.2.15, night lord G1 and a year carried by 5 Manikʼ.

The Calendar Round is the pair of the two cycles written together, and it does not repeat for 18,980 days, which is 52 Haab years and 73 turns of the 260 day round at the same time. The cross array is the Cruz Maya, five entries in a fixed order: the birth nawal at the centre, conception eight days before, destiny eight days after, and two arms six days after and six days before. Trimmed to its skeleton, the response looks like this.

{
  "calendarRound": "8 Men 8 Sotzʼ",
  "longCount": { "formatted": "12.18.17.2.15", "daysSinceEpoch": 1863775, "julianDayNumber": 2448058 },
  "yearBearer": { "daySignName": "Manikʼ", "number": 5 },
  "cross": [
    { "position": "center", "offsetDays": 0, "daySignName": "Men", "number": 8 },
    { "position": "conception", "offsetDays": -8, "daySignName": "Manikʼ", "number": 13 },
    { "position": "destiny", "offsetDays": 8, "daySignName": "Akʼbʼal", "number": 3 }
  ],
  "conventions": { "correlation": "gmt-584283", "yearBearerSystem": "classic" }
}

The Year Bearer is a typed choice too, because the three schools that name a Haab year share no day sign between them: a bearer on its own tells you which school produced it, so a silent default would be a school choice disguised as a fact.

How does the Aztec count sit beside the Maya one?

They are two 260 day counts with the same structure, thirteen coefficients against twenty signs, under different names and different anchors, and both ship on the same key. POST /mesoamerican-astrology/aztec/tonalpohualli returns the Nahuatl day sign, its gloss, its world direction, the coefficient and the trecena. On the default correlation the two counts land on the same coefficient and the same position in the twenty, which is what let the 1521 date above check the Maya side and the Aztec side at once.

The Aztec family deliberately returns fewer fields, and a scope sentence on every response says which ones and why: where the reference sources disagree, nothing ships rather than a guess. Readings come back in the reader language on every endpoint here, which matters more in this domain than most, because the living daykeeping audience is in Guatemala and Mexico. Adding ?lang=es to the same call returns the composed prose in Spanish while the machine layer holds still, here trimmed to two of the translated fields:

{
  "daySign": "men",
  "daySignName": "Men",
  "daySignKiche": "TZʼIKIN",
  "number": 8,
  "reading": {
    "keynote": "El nahual Men, llamado TZʼIKIN en la tradición de los guardianes del día de las tierras altas, es el águila, la mirada de largo alcance tomada desde lo bastante alto para ver todo el valle. El signo en sí se lee como águila.",
    "guidance": "Baja por un detalle. Una vista que nunca aterriza es paisaje, no conocimiento."
  }
}

Branch on daySign, render daySignName and the prose. That contract holds across all 18+ insight domains on one key, alongside Western astrology, Vedic astrology, transit forecasts, Human Design, Chinese astrology and feng shui, with typed SDKs for TypeScript, Python, PHP, C# and Go, drop in UI components and open source MIT templates included rather than sold separately.

FAQ

How do I find my Mayan zodiac sign?

Send your birth date to the Tzolkin endpoint and the day sign comes back with its coefficient, its trecena and a composed nawal reading in one response. RoxyAPI returns the sign in three namings at once, the standard Yucatec spelling, the sixteenth century form that older reference tables print, and the Kʼicheʼ name highland daykeepers use, so you can label it the way your audience expects. No birth time and no birthplace are needed, because the day sign is a function of the date alone.

Why do two Mayan day sign calculators give different answers?

Almost always the correlation constant, the number that ties the day count to a civil date. Several are published, they sit a few days apart, and a calculator that does not name the one it used cannot be checked. RoxyAPI accepts four of them as a typed request field and echoes the resolved value on every response, so a saved chart stays reproducible. The other common cause is a tool running a modern count rather than the classical one.

Is there an API for a Tzolkin day sign calculator?

Yes. RoxyAPI ships Mesoamerican astrology as a full domain of 18+ endpoints covering the Tzolkin day signs, the Haab year, the five position Long Count, the Calendar Round, the Lord of the Night, the Year Bearer, the five point Cruz Maya and the Aztec tonalpohualli. It sits on the same key as Western astrology, Vedic astrology, Human Design, Chinese astrology and every other RoxyAPI domain, with Remote MCP and typed SDKs included at no extra cost, and readings in 10+ languages.

Can I convert a Long Count date from an inscription?

Yes, in both directions. Send a dotted Long Count such as 9.12.11.5.18 and the RoxyAPI converter returns the civil date, the elapsed day count, the day number, the Calendar Round and the Lord of the Night. Send a date instead and it returns the Long Count. Dates before the 1582 Gregorian reform come back with a note explaining the calendar convention, which is the single most common source of a ten day disagreement between converters.

Does the Mayan astrology API work for historical dates?

Yes, and without losing accuracy, because a Mesoamerican day is a plain count of elapsed days rather than an astronomical lookup. A date call accepts any year from 1 to 4000, and the Long Count converter reaches the start of the count itself, 0.0.0.0.0, which comes back as 11 August 3114 BCE on the Calendar Round 4 Ajaw 8 Kumkʼu. Each of those is one request and returns in the same time as today. That is what makes RoxyAPI usable for epigraphy, museum and education software as well as for consumer day sign apps.

Conclusion

A Mayan day sign is one of the few readings in this field that a user can check by hand, which makes it one of the few where an unexplained answer is fatal. Publish the constant, publish the calendar convention, and the disagreement stops being a mystery and becomes a diff. The Mayan Astrology API returns both on every response, on the same flat all inclusive subscription as every other RoxyAPI domain. See pricing or read the Mesoamerican guide.