Mesoamerican Astrology API reference

Calculate Mayan astrology day signs, the Tzolkin sacred round, the Haab year, the full Long Count and the Aztec tonalpohualli from any date: day sign and coefficient, trecena, Calendar Round, Lord of the Night, Year Bearer and the five point Cruz Maya, each with a composed reading. The correlation constant that makes two Mayan calculators disagree is a typed parameter, and every response echoes the conventions it was computed under, so a saved chart stays reproducible. Both naming traditions ship on every sign, the Yucatec spelling and the Kʼicheʼ name daykeepers actually use, and readings come back in every language the API ships. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs.

18 endpoints. Product page. Typed SDKs in six languages carry every operation below.

Your API keyKept in this tab only. Without a key, a small daily allowance still answers every request below.

Mayan day sign for a date - Tzolkin calculator API

POST /api/v2/mesoamerican-astrology/mayan/tzolkin

Mayan astrology day sign calculator: returns the Tzolkin day sign, the coefficient 1 to 13 and the trecena for any Gregorian date, under the correlation living daykeepers use, with a composed nawal reading. Built for Mayan zodiac apps, daily energy feeds and AI agents answering what is my Mayan sign. Classical Maya count only, with the correlation echoed on every response so a saved reading stays reproducible.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`date` required	string (date)	Date in YYYY-MM-DD format, in the PROLEPTIC GREGORIAN calendar, extended backwards unchanged through the 1582 reform. Years 1 to 4000 are accepted. A reference converter that switches to the Julian calendar below the reform will disagree with a date before 15 October 1582 by ten or eleven days; that is a difference of input convention rather than of arithmetic, and passing the Julian equivalent to such a tool reproduces these values exactly. A single-digit month or day is accepted and zero padded.
`correlation`	string enum	Which correlation constant ties the day count to a civil date. This is the single choice that shifts every value in the response, so it is a parameter rather than a hidden default, and the resolved value comes back under conventions. "gmt-584283" is the commonly accepted constant and the default, and it is the one the major institutional converter runs on. "martinez-hernandez-584281" sits two days earlier, "astronomical-584285" two days later, and "martin-skidmore-584286" three days later, each shifting the Long Count by exactly its difference in days. Four of the eight published constants are offered: the other four sit tens of thousands of days away and are of historical interest only. The 584281 constant is the Martínez Hernández correlation, after Juan Martínez Hernández.

curl

curl -X POST "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/tzolkin" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2012-12-21"}'

Response fields

Field	Type	Description
`daySign` required	string	Machine identifier of the Tzolkin day sign, always lowercase ASCII Yucatec whatever the lang parameter says, so it stays safe to compare against in code. The twenty ids run imix, ik, akbal, kan, chikchan, kimi, manik, lamat, muluk, ok, chuwen, eb, ben, ix, men, kib, kaban, etznab, kawak, ajaw.
`daySignName` required	string	Display name of the day sign in the standard Maya orthography, where the ejective is written with a modifier letter rather than a typewriter quote. A proper noun carried as data, so it is identical under every lang.
`daySignClassic` required	string	The sixteenth century Yucatec spelling of the same sign, which is the form most printed reference tables and older sources use. Useful for matching a name a reader copied out of a book.
`daySignKiche` required	string	The Kʼicheʼ name of the same day from the living highland daykeeping tradition, which is the vocabulary a nawal reading in Guatemala uses. A parallel naming tradition rather than a translation, so it is identical under every lang.
`number` required	number	The Tzolkin coefficient, 1 to 13. This is the classical day number that runs alongside the twenty signs; it is not a rank and a 13 is not better than a 1. Nine of the thirteen carry a recorded character, which is returned separately.
`trecena` required	object	The thirteen day period this day belongs to. The trecena is the unit a daykeeper reads a run of days in, and the sign it opens on is what gives the whole period its character.
`trecena.number` required	number	Which of the twenty thirteen day periods this day falls in, 1 to 20. Trecena 1 opens on 1 Imix.
`trecena.dayOfTrecena` required	number	Position of this day inside its trecena, 1 to 13. Always equal to the coefficient, because a trecena is exactly one run of the coefficient.
`trecena.rulingSign` required	string	Machine identifier of the day sign the trecena opens on, which the tradition reads as colouring all thirteen of its days.
`trecena.rulingSignName` required	string	Display name of the sign the trecena opens on. A proper noun carried as data.
`date` required	string	Echo of the date the day was resolved from, in proleptic Gregorian.
`reading` required	object	The composed nawal reading for this day: the sign, what the coefficient contributes, and what the sign does well and badly.
`reading.keynote` required	string	The sign in one composed sentence: its name in both naming traditions, what it is about, and the glyph reading behind it. Composed per request from the sign components rather than stored whole, which is why it stays consistent with every other reading in the response.
`reading.numberReading` required	string	What the coefficient contributes. Nine of the thirteen carry a recorded character, banded as gentle, indifferent or violent; the other four carry none and this field says so rather than inventing one. The band ids are the source vocabulary, so violent names the days reserved for strong ceremony and defence and is not a warning.

Show all fieldsShow fewer fields

Field	Type	Description
`reading.numberBand`	string	Machine identifier of the recorded character of the coefficient: gentle, indifferent or violent. ABSENT for coefficients 4, 5, 6 and 10, which have no recorded character in any consulted source. Always English so it stays safe to switch on.
`reading.strengths` required	array of string	What the sign does well, as full sentences rather than keywords.
`reading.challenges` required	array of string	Where the same temperament costs the sign something. Each one is the shadow of a strength above rather than an unrelated flaw.
`reading.guidance` required	string	The one thing worth doing differently under this sign.
`conventions` required	object	The conventions this answer was computed under, echoed so the result is self describing. Only the correlation is echoed here, because it is the only switch this route takes.
`conventions.correlation` required	string	The correlation constant actually applied, whether it was requested or defaulted. Store this beside any Maya date you persist: the same civil date resolves to a different Long Count under each constant, and a date with no correlation recorded cannot be reproduced.

Example response

{
  "daySign": "ajaw",
  "daySignName": "Ajaw",
  "daySignClassic": "Ahau",
  "daySignKiche": "AJPUʼ",
  "number": 4,
  "trecena": {
    "number": 20,
    "dayOfTrecena": 4,
    "rulingSign": "kawak",
    "rulingSignName": "Kawak"
  },
  "date": "2012-12-21",
  "reading": {
    "keynote": "The nawal Ajaw, called AJPUʼ in the highland daykeeping tradition, is the sun at its height, the completed day and the authority that comes with finishing. The sign itself is read as lord, ruler, sun.",
    "numberReading": "The coefficient 4 has no character recorded for it in the sources this API is built on, so no reading is offered for the number alone. The sign carries the day.",
    "numberBand": "gentle",
    "strengths": [
      "Finishes what was started and lets the result be seen"
    ],
    "challenges": [
      "Needs the light on it and dims when the light moves"
    ],
    "guidance": "Give the credit away once today. A sun that shines only on itself lights nothing."
  },
  "conventions": {
    "correlation": "gmt-584283"
  }
}

Generate a Mayan chart - Tzolkin, Haab and Long Count calculator API

POST /api/v2/mesoamerican-astrology/mayan/chart

Mayan astrology birth chart from one date: the Tzolkin day sign and coefficient, the Haab date, the full Long Count with its day count, the Calendar Round, the Lord of the Night, the Year Bearer of the Haab year and the five point Cruz Maya, each with composed readings. Built for nawal readings, birth chart features and multi domain spiritual apps that show a Mayan card beside a natal chart. Every school split in the domain is a typed parameter and comes back echoed, so the chart can be reproduced exactly.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`date` required	string (date)	Date in YYYY-MM-DD format, in the PROLEPTIC GREGORIAN calendar, extended backwards unchanged through the 1582 reform. Years 1 to 4000 are accepted. A reference converter that switches to the Julian calendar below the reform will disagree with a date before 15 October 1582 by ten or eleven days; that is a difference of input convention rather than of arithmetic, and passing the Julian equivalent to such a tool reproduces these values exactly. A single-digit month or day is accepted and zero padded.
`correlation`	string enum	Which correlation constant ties the day count to a civil date. This is the single choice that shifts every value in the response, so it is a parameter rather than a hidden default, and the resolved value comes back under conventions. "gmt-584283" is the commonly accepted constant and the default, and it is the one the major institutional converter runs on. "martinez-hernandez-584281" sits two days earlier, "astronomical-584285" two days later, and "martin-skidmore-584286" three days later, each shifting the Long Count by exactly its difference in days. Four of the eight published constants are offered: the other four sit tens of thousands of days away and are of historical interest only. The 584281 constant is the Martínez Hernández correlation, after Juan Martínez Hernández.
`yearBearerSystem`	string enum	Which Haab day is read as the start of the year when naming its Year Bearer. Only four of the twenty day signs can ever carry a year, and which four depends entirely on this choice, so the three schools never agree. "classic" reads the seating of Pop and is the default, because it is the set highland daykeepers still use; its four bearers are Ikʼ, Manikʼ, Ebʼ and Kabʼan. "campeche" reads 1 Pop and gives Akʼbʼal, Lamat, Bʼen and Etzʼnabʼ. "colonial-yucatec" reads 2 Pop and gives Kʼan, Muluk, Ix and Kawak. The three sets share no member, so a bearer alone tells you which school produced it.

curl

curl -X POST "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/chart" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2012-12-21"}'

Response fields

Field	Type	Description
`date` required	string	Echo of the date the chart was computed from, in proleptic Gregorian.
`tzolkin` required	object	The 260 day sacred round: the day sign, its coefficient and the trecena it falls in. This is the cycle a nawal reading is built on.
`tzolkin.daySign` required	string	Machine identifier of the Tzolkin day sign, always lowercase ASCII Yucatec whatever the lang parameter says, so it stays safe to compare against in code. The twenty ids run imix, ik, akbal, kan, chikchan, kimi, manik, lamat, muluk, ok, chuwen, eb, ben, ix, men, kib, kaban, etznab, kawak, ajaw.
`tzolkin.daySignName` required	string	Display name of the day sign in the standard Maya orthography, where the ejective is written with a modifier letter rather than a typewriter quote. A proper noun carried as data, so it is identical under every lang.
`tzolkin.daySignClassic` required	string	The sixteenth century Yucatec spelling of the same sign, which is the form most printed reference tables and older sources use. Useful for matching a name a reader copied out of a book.
`tzolkin.daySignKiche` required	string	The Kʼicheʼ name of the same day from the living highland daykeeping tradition, which is the vocabulary a nawal reading in Guatemala uses. A parallel naming tradition rather than a translation, so it is identical under every lang.
`tzolkin.number` required	number	The Tzolkin coefficient, 1 to 13. This is the classical day number that runs alongside the twenty signs; it is not a rank and a 13 is not better than a 1. Nine of the thirteen carry a recorded character, which is returned separately.
`tzolkin.trecena` required	object	The thirteen day period this day belongs to. The trecena is the unit a daykeeper reads a run of days in, and the sign it opens on is what gives the whole period its character.
`tzolkin.trecena.number` required	number	Which of the twenty thirteen day periods this day falls in, 1 to 20. Trecena 1 opens on 1 Imix.
`tzolkin.trecena.dayOfTrecena` required	number	Position of this day inside its trecena, 1 to 13. Always equal to the coefficient, because a trecena is exactly one run of the coefficient.
`tzolkin.trecena.rulingSign` required	string	Machine identifier of the day sign the trecena opens on, which the tradition reads as colouring all thirteen of its days.
`tzolkin.trecena.rulingSignName` required	string	Display name of the sign the trecena opens on. A proper noun carried as data.
`tzolkin.reading` required	object	The composed nawal reading for the Tzolkin day.
`tzolkin.reading.keynote` required	string	The sign in one composed sentence: its name in both naming traditions, what it is about, and the glyph reading behind it. Composed per request from the sign components rather than stored whole, which is why it stays consistent with every other reading in the response.

Show all fieldsShow fewer fields

Field	Type	Description
`tzolkin.reading.numberReading` required	string	What the coefficient contributes. Nine of the thirteen carry a recorded character, banded as gentle, indifferent or violent; the other four carry none and this field says so rather than inventing one. The band ids are the source vocabulary, so violent names the days reserved for strong ceremony and defence and is not a warning.
`tzolkin.reading.numberBand`	string	Machine identifier of the recorded character of the coefficient: gentle, indifferent or violent. ABSENT for coefficients 4, 5, 6 and 10, which have no recorded character in any consulted source. Always English so it stays safe to switch on.
`tzolkin.reading.strengths` required	array of string	What the sign does well, as full sentences rather than keywords.
`tzolkin.reading.challenges` required	array of string	Where the same temperament costs the sign something. Each one is the shadow of a strength above rather than an unrelated flaw.
`tzolkin.reading.guidance` required	string	The one thing worth doing differently under this sign.
`haab` required	object	The 365 day vague year: eighteen periods of twenty days plus the five days of Wayebʼ. This is the agricultural year the Tzolkin runs against.
`haab.month` required	string	Machine identifier of the Haab period, always lowercase ASCII. The nineteen ids run pop, wo, sip, sotz, sek, xul, yaxkin, mol, chen, yax, sak, keh, mak, kankin, muwan, pax, kayab, kumku, wayeb.
`haab.monthName` required	string	Display name of the Haab period in the standard orthography. A proper noun carried as data, so it is identical under every lang.
`haab.monthClassic` required	string	The sixteenth century Yucatec spelling of the same period, which is the form most printed tables use.
`haab.day` required	number	Day inside the period, 0 to 19, or 0 to 4 in Wayebʼ. Day 0 is a real date and is called the seating of the period, so a Haab month has no day 20. Numbering from 1 instead is the usual way to be one day wrong on every Haab date.
`haab.dayOfYear` required	number	Day of the 365 day Haab year, 0 to 364. The Haab has no leap day at all, so it drifts against the solar year by about a day every four years and there is nothing to correct.
`haab.reading` required	string	Composed reading of the Haab date, which reads differently on the seating day of a period.
`longCount` required	object	The linear day count from the mythological start of the era, written in five positions. Unlike the two round calendars this one never repeats, which is what lets an inscription name an absolute date.
`longCount.formatted` required	string	The dotted Long Count, most significant position first. This is the spelling every reference converter and every inscription uses.
`longCount.baktun` required	number	Baktun, the highest of the five positions. One baktun is 144,000 days.
`longCount.katun` required	number	Katun, 0 to 19. One katun is 7,200 days, roughly twenty years.
`longCount.tun` required	number	Tun, 0 to 19. One tun is 360 days, which is why this position sits roughly a year apart.
`longCount.winal` required	number	Winal, 0 to 17 and never 19. This is the one position that is not base twenty: eighteen winal make a tun, which is what keeps the tun near a solar year.
`longCount.kin` required	number	Kin, 0 to 19. One kin is one day.
`longCount.daysSinceEpoch` required	number	The whole Long Count as a single integer count of days from the epoch. Subtracting two of these is the correct way to measure an interval, and it is the number the Tzolkin, the Haab and the night lord are all derived from.
`longCount.julianDayNumber` required	number	Julian Day Number of the same day, which is the bridge between this count and any other calendar. Adding the correlation constant to daysSinceEpoch gives exactly this.
`calendarRound` required	string	The Tzolkin and Haab dates written together, which is how a Classic inscription names a day. The pair repeats every 18,980 days, a little under 52 years, so a Calendar Round alone is ambiguous beyond one lifetime and the Long Count is what disambiguates it.
`lordOfNight` required	object	The nine day cycle that runs beside the other three. The nine are identified and the cycle is unambiguous, but no source records what the Maya called them, so this API publishes the labels rather than borrowing names from a neighbouring culture.
`lordOfNight.label` required	string	Which of the nine Lords of the Night governs this day, G1 to G9. The cycle steps forward one per day and closes every nine.
`lordOfNight.reading` required	string	One line on the night lord, including why the nine carry labels rather than names.
`yearBearer` required	object	The Tzolkin day that names the Haab year this date falls in, under the requested school.
`yearBearer.daySign` required	string	Machine identifier of the day sign carrying the Haab year this date falls in. Only four of the twenty can ever carry a year, and which four depends on the school.
`yearBearer.daySignName` required	string	Display name of the bearing sign. A proper noun carried as data.
`yearBearer.number` required	number	Coefficient of the bearing day, 1 to 13. The coefficient advances by one each Haab year, which is what makes the bearer and the number together repeat only every 52 years.
`yearBearer.reading` required	string	One line on the year bearer that names the school it was read under, because the three schools name three different bearers for the same year.
`cross` required	array of object	The Cruz Maya, the five point nawal cross, with source convention. This is a LIVING DAYKEEPER PRACTICE rather than an archaeological reconstruction: no academic source describes a five point cross, and the day offsets here were measured against two independent practitioner calculators that agree. It is published because practitioners use it, and it is labelled because that is what honesty about a source looks like.
`cross[].position` required	string	Which point of the cross this is: center, conception, destiny, left or right. Always English so it stays safe to switch on. The arms are published as left and right and carry no gender, because the sources that agree on the SIGNS disagree on which arm is masculine and which feminine.
`cross[].offsetDays` required	number	Days from the birth day to this arm. Negative is before the birth day. Conception is minus eight, destiny plus eight, the left arm plus six and the right arm minus six.
`cross[].daySign` required	string	Machine identifier of the day sign standing at this point.
`cross[].daySignName` required	string	Display name of the sign at this point. A proper noun carried as data.
`cross[].daySignKiche` required	string	Kʼicheʼ name of the same sign, which is the vocabulary a cross is normally read in.
`cross[].number` required	number	Coefficient of the day at this point, 1 to 13.
`cross[].reading` required	string	One line on what this point of the cross is read as.
`summary` required	string	One composed sentence placing the day in all three calendars, for a card headline or a chat reply.
`conventions` required	object	The conventions this chart was computed under, echoed so the result is self describing. Store both beside any chart you persist.
`conventions.correlation` required	string	The correlation constant actually applied, whether it was requested or defaulted. Store this beside any Maya date you persist: the same civil date resolves to a different Long Count under each constant, and a date with no correlation recorded cannot be reproduced.
`conventions.yearBearerSystem` required	string	The Year Bearer school actually applied. The three schools name three different bearers for the same Haab year, so a bearer stored without this value cannot be checked against anything.

Example response

{
  "date": "2012-12-21",
  "tzolkin": {
    "daySign": "ajaw",
    "daySignName": "Ajaw",
    "daySignClassic": "Ahau",
    "daySignKiche": "AJPUʼ",
    "number": 4,
    "trecena": {
      "number": 20,
      "dayOfTrecena": 4,
      "rulingSign": "kawak",
      "rulingSignName": "Kawak"
    },
    "reading": {
      "keynote": "The nawal Ajaw, called AJPUʼ in the highland daykeeping tradition, is the sun at its height, the completed day and the authority that comes with finishing. The sign itself is read as lord, ruler, sun.",
      "numberReading": "The coefficient 4 has no character recorded for it in the sources this API is built on, so no reading is offered for the number alone. The sign carries the day.",
      "numberBand": "gentle",
      "strengths": [
        "Finishes what was started and lets the result be seen"
      ],
      "challenges": [
        "Needs the light on it and dims when the light moves"
      ],
      "guidance": "Give the credit away once today. A sun that shines only on itself lights nothing."
    }
  },
  "haab": {
    "month": "kankin",
    "monthName": "Kʼankʼin",
    "monthClassic": "Kankin",
    "day": 3,
    "dayOfYear": 263,
    "reading": "The Haab date is 3 Kʼankʼin, inside a period read this way: The yellow sun, ripening light, where the year turns toward its harvest."
  },
  "longCount": {
    "formatted": "13.0.0.0.0",
    "baktun": 13,
    "katun": 0,
    "tun": 0,
    "winal": 0,
    "kin": 0,
    "daysSinceEpoch": 1872000,
    "julianDayNumber": 2456283
  },
  "calendarRound": "4 Ajaw 3 Kʼankʼin",
  "lordOfNight": {
    "label": "G9",
    "reading": "The night belongs to G9 of the nine, a cycle that turns one step every day and closes every nine. The Maya names for the nine were never recorded, so the cycle is published by its glyph labels alone."
  },
  "yearBearer": {
    "daySign": "kaban",
    "daySignName": "Kabʼan",
    "number": 5,
    "reading": "The Haab year is carried by 5 Kabʼan, read at the seating of Pop. This is the Classic set, and it is the one highland daykeepers still run today."
  },
  "cross": [
    {
      "position": "conception",
      "offsetDays": -8,
      "daySign": "chikchan",
      "daySignName": "Chikchan",
      "daySignKiche": "KAN",
      "number": 9,
      "reading": "The conception arm, eight days before the birth day, is 9 Chikchan. It is read as the root the life is drawn from."
    }
  ],
  "summary": "This day is 4 Ajaw 3 Kʼankʼin, Long Count 13.0.0.0.0. The nawal is Ajaw, the sun at its height, the completed day and the authority that comes with finishing, carried on the coefficient 4.",
  "conventions": {
    "correlation": "gmt-584283",
    "yearBearerSystem": "classic"
  }
}

Convert a Maya Long Count - Long Count calendar converter API

POST /api/v2/mesoamerican-astrology/mayan/long-count/convert

Maya Long Count converter that runs both ways: give it a Gregorian date and it returns the Long Count, give it a dotted Long Count and it returns the date. Every answer carries the Julian Day Number, the elapsed day count and the Calendar Round, and the correlation constant is a typed parameter so a value can be matched against any published inscription reading. Built for epigraphy tools, museum and education apps, and anything that has to place a Maya date on a civil calendar.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`date`	string (date)	Proleptic Gregorian date to convert INTO a Long Count. Supply this or longCount, never both and never neither.
`longCount`	string	Dotted Long Count to convert INTO a date, written baktun.katun.tun.winal.kin. Each position is bounded by its own base, and the winal counts to 17 rather than to 19 because eighteen winal make a tun, so 9.12.11.18.0 is rejected as a date that does not exist. Supply this or date, never both and never neither.
`correlation`	string enum	Which correlation constant ties the day count to a civil date. This is the single choice that shifts every value in the response, so it is a parameter rather than a hidden default, and the resolved value comes back under conventions. "gmt-584283" is the commonly accepted constant and the default, and it is the one the major institutional converter runs on. "martinez-hernandez-584281" sits two days earlier, "astronomical-584285" two days later, and "martin-skidmore-584286" three days later, each shifting the Long Count by exactly its difference in days. Four of the eight published constants are offered: the other four sit tens of thousands of days away and are of historical interest only. The 584281 constant is the Martínez Hernández correlation, after Juan Martínez Hernández.

curl

curl -X POST "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/long-count/convert" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2012-12-21","longCount":"13.0.0.0.0","correlation":"gmt-584283"}'

Response fields

Field	Type	Description
`date` required	string	The proleptic Gregorian date, echoed when it was the input and computed when the Long Count was.
`longCount` required	string	The dotted Long Count, echoed when it was the input and computed when the date was.
`daysSinceEpoch` required	number	The Long Count as one integer count of days from the epoch. Subtracting two of these is the correct way to measure an interval between two Maya dates.
`julianDayNumber` required	number	Julian Day Number of the same day, which is the bridge to any other calendar. It is exactly daysSinceEpoch plus the correlation constant.
`calendarRound` required	string	The Tzolkin and Haab dates written together, which is how an inscription names a day. The pair repeats every 18,980 days, so it is ambiguous beyond about 52 years and the Long Count is what fixes it.
`lordOfNight` required	string	Which of the nine Lords of the Night governs the day, G1 to G9. The nine carry glyph labels rather than names because no source records what the Maya called them.
`note`	string	Present ONLY for a date before the Gregorian reform, where the input convention is the usual reason two converters disagree. Absent otherwise, so its presence is itself the signal.
`conventions` required	object	The conventions this conversion was computed under, echoed so the result is self describing.
`conventions.correlation` required	string	The correlation constant actually applied, whether it was requested or defaulted. Store this beside any Maya date you persist: the same civil date resolves to a different Long Count under each constant, and a date with no correlation recorded cannot be reproduced.

Example response

{
  "date": "2012-12-21",
  "longCount": "13.0.0.0.0",
  "daysSinceEpoch": 1872000,
  "julianDayNumber": 2456283,
  "calendarRound": "4 Ajaw 3 Kʼankʼin",
  "lordOfNight": "G9",
  "note": "This date precedes the Gregorian reform of 15 October 1582. 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"
  }
}

Daily Mayan energy reading - Tzolkin day sign of the day API

GET /api/v2/mesoamerican-astrology/mayan/daily

Mayan energy of the day: the Tzolkin day sign, its coefficient and its trecena for today or for any date you name, with a composed reading. Content is fixed for a given date and rolls over at midnight UTC, so a daily feed can cache it safely and an editorial calendar can be filled weeks ahead. Built for daily energy widgets, nawal of the day feeds and chatbot answers about what today carries.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.
`date` query	string (date)	Date in YYYY-MM-DD format, in the PROLEPTIC GREGORIAN calendar, extended backwards unchanged through the 1582 reform. Years 1 to 4000 are accepted. A reference converter that switches to the Julian calendar below the reform will disagree with a date before 15 October 1582 by ten or eleven days; that is a difference of input convention rather than of arithmetic, and passing the Julian equivalent to such a tool reproduces these values exactly. A single-digit month or day is accepted and zero padded. Defaults to the current day in UTC.
`correlation` query	string enum	Which correlation constant ties the day count to a civil date. This is the single choice that shifts every value in the response, so it is a parameter rather than a hidden default, and the resolved value comes back under conventions. "gmt-584283" is the commonly accepted constant and the default, and it is the one the major institutional converter runs on. "martinez-hernandez-584281" sits two days earlier, "astronomical-584285" two days later, and "martin-skidmore-584286" three days later, each shifting the Long Count by exactly its difference in days. Four of the eight published constants are offered: the other four sit tens of thousands of days away and are of historical interest only. The 584281 constant is the Martínez Hernández correlation, after Juan Martínez Hernández. Default `gmt-584283`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/daily" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`daySign` required	string	Machine identifier of the Tzolkin day sign, always lowercase ASCII Yucatec whatever the lang parameter says, so it stays safe to compare against in code. The twenty ids run imix, ik, akbal, kan, chikchan, kimi, manik, lamat, muluk, ok, chuwen, eb, ben, ix, men, kib, kaban, etznab, kawak, ajaw.
`daySignName` required	string	Display name of the day sign in the standard Maya orthography, where the ejective is written with a modifier letter rather than a typewriter quote. A proper noun carried as data, so it is identical under every lang.
`daySignClassic` required	string	The sixteenth century Yucatec spelling of the same sign, which is the form most printed reference tables and older sources use. Useful for matching a name a reader copied out of a book.
`daySignKiche` required	string	The Kʼicheʼ name of the same day from the living highland daykeeping tradition, which is the vocabulary a nawal reading in Guatemala uses. A parallel naming tradition rather than a translation, so it is identical under every lang.
`number` required	number	The Tzolkin coefficient, 1 to 13. This is the classical day number that runs alongside the twenty signs; it is not a rank and a 13 is not better than a 1. Nine of the thirteen carry a recorded character, which is returned separately.
`trecena` required	object	The thirteen day period this day belongs to. The trecena is the unit a daykeeper reads a run of days in, and the sign it opens on is what gives the whole period its character.
`trecena.number` required	number	Which of the twenty thirteen day periods this day falls in, 1 to 20. Trecena 1 opens on 1 Imix.
`trecena.dayOfTrecena` required	number	Position of this day inside its trecena, 1 to 13. Always equal to the coefficient, because a trecena is exactly one run of the coefficient.
`trecena.rulingSign` required	string	Machine identifier of the day sign the trecena opens on, which the tradition reads as colouring all thirteen of its days.
`trecena.rulingSignName` required	string	Display name of the sign the trecena opens on. A proper noun carried as data.
`date` required	string	Date of this reading. Echoes the date requested, or the current day in UTC when it was omitted.
`overview` required	string	What the day carries, placing it inside its trecena as well as naming it. Composed per request, so it stays consistent with the reading below rather than being a second opinion.
`reading` required	object	The composed nawal reading for the day sign in force.
`reading.keynote` required	string	The sign in one composed sentence: its name in both naming traditions, what it is about, and the glyph reading behind it. Composed per request from the sign components rather than stored whole, which is why it stays consistent with every other reading in the response.

Show all fieldsShow fewer fields

Field	Type	Description
`reading.numberReading` required	string	What the coefficient contributes. Nine of the thirteen carry a recorded character, banded as gentle, indifferent or violent; the other four carry none and this field says so rather than inventing one. The band ids are the source vocabulary, so violent names the days reserved for strong ceremony and defence and is not a warning.
`reading.numberBand`	string	Machine identifier of the recorded character of the coefficient: gentle, indifferent or violent. ABSENT for coefficients 4, 5, 6 and 10, which have no recorded character in any consulted source. Always English so it stays safe to switch on.
`reading.strengths` required	array of string	What the sign does well, as full sentences rather than keywords.
`reading.challenges` required	array of string	Where the same temperament costs the sign something. Each one is the shadow of a strength above rather than an unrelated flaw.
`reading.guidance` required	string	The one thing worth doing differently under this sign.
`conventions` required	object	The conventions this reading was computed under, echoed so the result is self describing.
`conventions.correlation` required	string	The correlation constant actually applied, whether it was requested or defaulted. Store this beside any Maya date you persist: the same civil date resolves to a different Long Count under each constant, and a date with no correlation recorded cannot be reproduced.

Example response

{
  "daySign": "ajaw",
  "daySignName": "Ajaw",
  "daySignClassic": "Ahau",
  "daySignKiche": "AJPUʼ",
  "number": 4,
  "trecena": {
    "number": 20,
    "dayOfTrecena": 4,
    "rulingSign": "kawak",
    "rulingSignName": "Kawak"
  },
  "date": "2026-09-02",
  "overview": "Today is 2 Akʼbʼal, day 2 of the trecena that opened on 1 Ikʼ. The day is coloured by the dark hour before first light, where a thing is decided but not yet visible.",
  "reading": {
    "keynote": "The nawal Ajaw, called AJPUʼ in the highland daykeeping tradition, is the sun at its height, the completed day and the authority that comes with finishing. The sign itself is read as lord, ruler, sun.",
    "numberReading": "The coefficient 4 has no character recorded for it in the sources this API is built on, so no reading is offered for the number alone. The sign carries the day.",
    "numberBand": "gentle",
    "strengths": [
      "Finishes what was started and lets the result be seen"
    ],
    "challenges": [
      "Needs the light on it and dims when the light moves"
    ],
    "guidance": "Give the credit away once today. A sun that shines only on itself lights nothing."
  },
  "conventions": {
    "correlation": "gmt-584283"
  }
}

Monthly Tzolkin calendar grid - Maya calendar month API

GET /api/v2/mesoamerican-astrology/mayan/calendar/monthly

Mayan calendar grid for a whole civil month: every day of the month with its Tzolkin day sign and coefficient, its trecena, its Haab date and its Long Count. One call fills a monthly grid that would otherwise take a request per day, and the answer is fixed for any month that has already begun. Built for calendar widgets, editorial planners and any app that shows a month of Maya dates at once.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.
`year` query	integer	Gregorian year of the grid, 1900 to 2100. Defaults to the current year in UTC. Wider historical ranges are available on the single date routes, which are not bounded to this window.
`month` query	integer	Calendar month of the grid, 1 to 12. Defaults to the current month in UTC.
`correlation` query	string enum	Which correlation constant ties the day count to a civil date. This is the single choice that shifts every value in the response, so it is a parameter rather than a hidden default, and the resolved value comes back under conventions. "gmt-584283" is the commonly accepted constant and the default, and it is the one the major institutional converter runs on. "martinez-hernandez-584281" sits two days earlier, "astronomical-584285" two days later, and "martin-skidmore-584286" three days later, each shifting the Long Count by exactly its difference in days. Four of the eight published constants are offered: the other four sit tens of thousands of days away and are of historical interest only. The 584281 constant is the Martínez Hernández correlation, after Juan Martínez Hernández. Default `gmt-584283`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/calendar/monthly" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`year` required	number	Year of the grid, echoed or defaulted to the current year in UTC.
`month` required	number	Month of the grid, echoed or defaulted to the current month in UTC.
`total` required	number	Number of days in the grid, which is the length of the civil month. Every day of the month appears exactly once and none is repeated.
`days` required	array of object	The days of the month in calendar order, one row per day. Every date in the month is present exactly once, which is what makes this safe to render straight into a grid.
`days[].date` required	string	Calendar date of this row, in proleptic Gregorian.
`days[].daySign` required	string	Machine identifier of the Tzolkin day sign, always lowercase ASCII Yucatec, so it stays safe to compare against in code.
`days[].daySignName` required	string	Display name of the day sign. A proper noun carried as data, identical under every lang.
`days[].number` required	number	The Tzolkin coefficient for this day, 1 to 13.
`days[].trecena` required	number	Which of the twenty thirteen day periods this day falls in, 1 to 20. Consecutive rows share a trecena until the period turns.
`days[].haab` required	string	The Haab date, written as the day inside its period followed by the period name. Day 0 is the seating of a period and is a real date.
`days[].longCount` required	string	The dotted Long Count for this day. Consecutive rows differ by exactly one kin.
`conventions` required	object	The conventions this grid was computed under, echoed so the result is self describing.
`conventions.correlation` required	string	The correlation constant actually applied, whether it was requested or defaulted. Store this beside any Maya date you persist: the same civil date resolves to a different Long Count under each constant, and a date with no correlation recorded cannot be reproduced.

Example response

{
  "year": 2026,
  "month": 9,
  "total": 30,
  "days": [
    {
      "date": "2026-09-02",
      "daySign": "akbal",
      "daySignName": "Akʼbʼal",
      "number": 2,
      "trecena": 18,
      "haab": "16 Mol",
      "longCount": "13.0.13.16.3"
    }
  ],
  "conventions": {
    "correlation": "gmt-584283"
  }
}

Mayan nawal compatibility - Tzolkin pair analysis API

POST /api/v2/mesoamerican-astrology/mayan/compatibility

Mayan compatibility between two birth dates, published as its parts rather than as a verdict: both nawals with their coefficients and trecenas, the five structural ties the pair either has or does not, the weight each tie carries, and a composite score built from them. Built for matchmaking features, relationship reports and compatibility widgets that need to show their working. The scoring weights are stated on every response so a caller can re-derive the number or replace it.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`personA` required	object	The first person, by birth date. Only a date is needed: the Tzolkin is a day count, so no time, timezone or place changes the answer.
`personA.date` required	string (date)	Date in YYYY-MM-DD format, in the PROLEPTIC GREGORIAN calendar, extended backwards unchanged through the 1582 reform. Years 1 to 4000 are accepted. A reference converter that switches to the Julian calendar below the reform will disagree with a date before 15 October 1582 by ten or eleven days; that is a difference of input convention rather than of arithmetic, and passing the Julian equivalent to such a tool reproduces these values exactly. A single-digit month or day is accepted and zero padded.
`personB` required	object	The second person, by birth date. The comparison is symmetric except for the cross tie, which is checked in both directions.
`personB.date` required	string (date)	Date in YYYY-MM-DD format, in the PROLEPTIC GREGORIAN calendar, extended backwards unchanged through the 1582 reform. Years 1 to 4000 are accepted. A reference converter that switches to the Julian calendar below the reform will disagree with a date before 15 October 1582 by ten or eleven days; that is a difference of input convention rather than of arithmetic, and passing the Julian equivalent to such a tool reproduces these values exactly. A single-digit month or day is accepted and zero padded.
`correlation`	string enum	Which correlation constant ties the day count to a civil date. This is the single choice that shifts every value in the response, so it is a parameter rather than a hidden default, and the resolved value comes back under conventions. "gmt-584283" is the commonly accepted constant and the default, and it is the one the major institutional converter runs on. "martinez-hernandez-584281" sits two days earlier, "astronomical-584285" two days later, and "martin-skidmore-584286" three days later, each shifting the Long Count by exactly its difference in days. Four of the eight published constants are offered: the other four sit tens of thousands of days away and are of historical interest only. The 584281 constant is the Martínez Hernández correlation, after Juan Martínez Hernández.
`directionScheme`	string enum	Which reading of the world direction and colour to serve for a day sign. The two published assignments differ by exactly one quarter turn on all twenty signs, so neither is a rounding of the other and a silent pick would be a school choice. "madrid-codex" is the codex reading and the default; "landa" is the sixteenth century assignment recorded beside it.

curl

curl -X POST "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/compatibility" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"personA":{"date":"2012-12-21"},"personB":{"date":"2012-12-21"}}'

Response fields

Field	Type	Description
`personA` required	object	The Tzolkin day the first person was born on.
`personA.daySign` required	string	Machine identifier of the Tzolkin day sign, always lowercase ASCII Yucatec whatever the lang parameter says, so it stays safe to compare against in code. The twenty ids run imix, ik, akbal, kan, chikchan, kimi, manik, lamat, muluk, ok, chuwen, eb, ben, ix, men, kib, kaban, etznab, kawak, ajaw.
`personA.daySignName` required	string	Display name of the day sign in the standard Maya orthography, where the ejective is written with a modifier letter rather than a typewriter quote. A proper noun carried as data, so it is identical under every lang.
`personA.daySignClassic` required	string	The sixteenth century Yucatec spelling of the same sign, which is the form most printed reference tables and older sources use. Useful for matching a name a reader copied out of a book.
`personA.daySignKiche` required	string	The Kʼicheʼ name of the same day from the living highland daykeeping tradition, which is the vocabulary a nawal reading in Guatemala uses. A parallel naming tradition rather than a translation, so it is identical under every lang.
`personA.number` required	number	The Tzolkin coefficient, 1 to 13. This is the classical day number that runs alongside the twenty signs; it is not a rank and a 13 is not better than a 1. Nine of the thirteen carry a recorded character, which is returned separately.
`personA.trecena` required	object	The thirteen day period this day belongs to. The trecena is the unit a daykeeper reads a run of days in, and the sign it opens on is what gives the whole period its character.
`personA.trecena.number` required	number	Which of the twenty thirteen day periods this day falls in, 1 to 20. Trecena 1 opens on 1 Imix.
`personA.trecena.dayOfTrecena` required	number	Position of this day inside its trecena, 1 to 13. Always equal to the coefficient, because a trecena is exactly one run of the coefficient.
`personA.trecena.rulingSign` required	string	Machine identifier of the day sign the trecena opens on, which the tradition reads as colouring all thirteen of its days.
`personA.trecena.rulingSignName` required	string	Display name of the sign the trecena opens on. A proper noun carried as data.
`personA.date` required	string	Echo of the first birth date.
`personB` required	object	The Tzolkin day the second person was born on.
`personB.daySign` required	string	Machine identifier of the Tzolkin day sign, always lowercase ASCII Yucatec whatever the lang parameter says, so it stays safe to compare against in code. The twenty ids run imix, ik, akbal, kan, chikchan, kimi, manik, lamat, muluk, ok, chuwen, eb, ben, ix, men, kib, kaban, etznab, kawak, ajaw.

Show all fieldsShow fewer fields

Field	Type	Description
`personB.daySignName` required	string	Display name of the day sign in the standard Maya orthography, where the ejective is written with a modifier letter rather than a typewriter quote. A proper noun carried as data, so it is identical under every lang.
`personB.daySignClassic` required	string	The sixteenth century Yucatec spelling of the same sign, which is the form most printed reference tables and older sources use. Useful for matching a name a reader copied out of a book.
`personB.daySignKiche` required	string	The Kʼicheʼ name of the same day from the living highland daykeeping tradition, which is the vocabulary a nawal reading in Guatemala uses. A parallel naming tradition rather than a translation, so it is identical under every lang.
`personB.number` required	number	The Tzolkin coefficient, 1 to 13. This is the classical day number that runs alongside the twenty signs; it is not a rank and a 13 is not better than a 1. Nine of the thirteen carry a recorded character, which is returned separately.
`personB.trecena` required	object	The thirteen day period this day belongs to. The trecena is the unit a daykeeper reads a run of days in, and the sign it opens on is what gives the whole period its character.
`personB.trecena.number` required	number	Which of the twenty thirteen day periods this day falls in, 1 to 20. Trecena 1 opens on 1 Imix.
`personB.trecena.dayOfTrecena` required	number	Position of this day inside its trecena, 1 to 13. Always equal to the coefficient, because a trecena is exactly one run of the coefficient.
`personB.trecena.rulingSign` required	string	Machine identifier of the day sign the trecena opens on, which the tradition reads as colouring all thirteen of its days.
`personB.trecena.rulingSignName` required	string	Display name of the sign the trecena opens on. A proper noun carried as data.
`personB.date` required	string	Echo of the second birth date.
`daysApart` required	number	How far apart the two days sit in the 260 day round, taken the short way round, so the value never exceeds 130. Two people on the same nawal are 0 apart.
`components` required	array of object	The five structural ties, in a fixed order, each either holding or not. Every one of them is a property of the count itself or of the measured daykeeper cross convention; what is ours is only the decision to weigh them together.
`components[].id` required	string	Which tie this row reports: same-sign, same-trecena, same-number, cross-partner or shared-direction. Always English so it stays safe to switch on.
`components[].holds` required	boolean	Whether this tie holds for the pair. Every component is returned whether it holds or not, so a caller can render the misses as well as the hits.
`components[].weight` required	number	Points this tie contributes to the score when it holds, and nothing when it does not. The weights are published rather than hidden precisely because the weighting is ours rather than traditional.
`components[].reading`	string	One line on what this tie means. Present ONLY when the tie holds, so a caller can render the hits without filtering and a miss carries no sentence to explain away.
`score` required	number	A RoxyAPI COMPOSITE, not a traditional rating. No classical source rates a pair of Tzolkin days, so this number is a floor of 45 plus the weight of every tie that holds, capped at 100. The components above are what is sourced; this is what we built out of them, and it is labelled so that nobody cites it as tradition.
`verdict` required	string	Coarse band the composite score falls in: excellent, strong, workable or reserved. Built for badges and filters that should not hard code a threshold against a number whose weighting may be tuned.
`summary` required	string	One composed sentence naming both nawals and the distance between them, for a headline above the component list. When no tie holds at all it says so, because that is the common case and a blank component list is not self explanatory.
`conventions` required	object	The conventions this comparison was computed under. The direction scheme is echoed because one of the five ties is read off the world directions, which the two schemes assign differently.
`conventions.correlation` required	string	The correlation constant actually applied, whether it was requested or defaulted. Store this beside any Maya date you persist: the same civil date resolves to a different Long Count under each constant, and a date with no correlation recorded cannot be reproduced.
`conventions.directionScheme` required	string	The direction reading actually applied. The two readings sit one quarter turn apart, so a direction stored without this value is ambiguous.

Example response

{
  "personA": {
    "daySign": "ajaw",
    "daySignName": "Ajaw",
    "daySignClassic": "Ahau",
    "daySignKiche": "AJPUʼ",
    "number": 4,
    "trecena": {
      "number": 20,
      "dayOfTrecena": 4,
      "rulingSign": "kawak",
      "rulingSignName": "Kawak"
    },
    "date": "1990-06-15"
  },
  "personB": {
    "daySign": "ajaw",
    "daySignName": "Ajaw",
    "daySignClassic": "Ahau",
    "daySignKiche": "AJPUʼ",
    "number": 4,
    "trecena": {
      "number": 20,
      "dayOfTrecena": 4,
      "rulingSign": "kawak",
      "rulingSignName": "Kawak"
    },
    "date": "1988-03-02"
  },
  "daysApart": 47,
  "components": [
    {
      "id": "same-trecena",
      "holds": true,
      "weight": 20,
      "reading": "Both days fall inside the same trecena, so the two lives are coloured by one ruling sign."
    }
  ],
  "score": 65,
  "verdict": "workable",
  "summary": "The pair sets Lamat against Ajaw, 47 days apart in the 260 day count.",
  "conventions": {
    "correlation": "gmt-584283",
    "directionScheme": "madrid-codex"
  }
}

Try it

lang

Request bodyJSON, as the example above shows it.

Not sent

List the 20 Mayan day signs - Tzolkin nawal catalogue API

GET /api/v2/mesoamerican-astrology/mayan/day-signs

Retrieve all twenty Tzolkin day signs in sequence order from Imix to Ajaw. Each entry returns the machine id, the name in the standard orthography, the sixteenth century spelling and the Kʼicheʼ name from the living daykeeping tradition, both published glosses, and the world direction and colour under the requested scheme. Built for nawal pickers, sign reference pages and any app that needs the whole set in one call.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.
`directionScheme` query	string enum	Which reading of the world direction and colour to serve for a day sign. The two published assignments differ by exactly one quarter turn on all twenty signs, so neither is a rounding of the other and a silent pick would be a school choice. "madrid-codex" is the codex reading and the default; "landa" is the sixteenth century assignment recorded beside it. Default `madrid-codex`.
`limit` query	integer	Maximum items to return per page. Range: 1-20, default 20. Default `20`.
`offset` query	integer	Number of items to skip for pagination. Default 0. Default `0`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/day-signs" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`total` required	number	Total signs in the cycle. Always 20; the Tzolkin sign set is closed.
`limit` required	number	Maximum items returned for this page.
`offset` required	number	Number of items skipped before this page.
`daySigns` required	array of object	Day signs for the current page, in sequence order. Use /mayan/day-signs/{id} for the full record with the composed reading, strengths, challenges and guidance.
`daySigns[].position` required	number	Place in the twenty sign sequence, 1 to 20, counting Imix as 1. The sequence never varies and is what every other cycle in the domain is indexed against.
`daySigns[].id` required	string	Machine identifier of the day sign, always lowercase ASCII Yucatec whatever the lang parameter says, so it stays safe to compare against in code and to use as a path parameter. The twenty ids run imix, ik, akbal, kan, chikchan, kimi, manik, lamat, muluk, ok, chuwen, eb, ben, ix, men, kib, kaban, etznab, kawak, ajaw.
`daySigns[].nameYucatec` required	string	Display name in the standard Maya orthography, where an ejective is written with a modifier letter rather than a typewriter quote. A proper noun carried as data, identical under every lang.
`daySigns[].nameClassic` required	string	The sixteenth century Yucatec spelling of the same sign, which is the form most printed reference tables and older books use.
`daySigns[].nameKiche` required	string	The Kʼicheʼ name from the living highland daykeeping tradition, which is the vocabulary a nawal reading in Guatemala uses. A parallel naming tradition rather than a translation, so it is identical under every lang.
`daySigns[].gloss` required	string	The short day-name association, translated in place because it is a common noun rather than a name. Two published readings of the twenty signs disagree on six of them, so the alternate reading ships beside this one rather than one being resolved away.
`daySigns[].glossAlternate` required	string	The glyph-table reading of the same sign, translated in place. On the six signs where the two readings disagree this is the one the composed prose follows, so a reading that seems to ignore the gloss above is doing so deliberately.
`daySigns[].direction` required	string	World direction this sign belongs to under the requested scheme: east, north, west or south. The twenty signs divide evenly into four groups of five, so exactly five signs share each quarter.
`daySigns[].color` required	string	Colour paired with the direction: red for east, white for north, black for west, yellow for south. Always English so it stays safe to key a palette off.
`conventions` required	object	The conventions this listing was served under. Only the direction scheme applies here, because it is the only field on a catalogue row that a school split moves.

Show all fieldsShow fewer fields

Field	Type	Description
`conventions.directionScheme` required	string	The direction reading actually applied. The two readings sit one quarter turn apart, so a direction stored without this value is ambiguous.

Example response

{
  "total": 20,
  "limit": 20,
  "offset": 0,
  "daySigns": [
    {
      "position": 1,
      "id": "imix",
      "nameYucatec": "Imix",
      "nameClassic": "Imix",
      "nameKiche": "IMOX",
      "gloss": "crocodile",
      "glossAlternate": "Naah Kan, the Primordial Snake; the essence of water",
      "direction": "north",
      "color": "white"
    }
  ],
  "conventions": {
    "directionScheme": "madrid-codex"
  }
}

Get one Mayan day sign - Nawal profile API

GET /api/v2/mesoamerican-astrology/mayan/day-signs/{id}

Retrieve the full profile of one Tzolkin day sign: both naming traditions, both published glosses, the world direction and colour under the requested scheme, a composed keynote, what the sign does well, where the same temperament costs it something, and one line of guidance. Built for nawal detail pages, sign cards and chatbot answers about a single Mayan sign.

Parameters

Parameter	Type	Description
`id` required path	string enum	Day sign id, case-insensitive and punctuation-insensitive. One of imix, ik, akbal, kan, chikchan, kimi, manik, lamat, muluk, ok, chuwen, eb, ben, ix, men, kib, kaban, etznab, kawak, ajaw.
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.
`directionScheme` query	string enum	Which reading of the world direction and colour to serve for a day sign. The two published assignments differ by exactly one quarter turn on all twenty signs, so neither is a rounding of the other and a silent pick would be a school choice. "madrid-codex" is the codex reading and the default; "landa" is the sixteenth century assignment recorded beside it. Default `madrid-codex`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/day-signs/imix" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`position` required	number	Place in the twenty sign sequence, 1 to 20, counting Imix as 1. The sequence never varies and is what every other cycle in the domain is indexed against.
`id` required	string	Machine identifier of the day sign, always lowercase ASCII Yucatec whatever the lang parameter says, so it stays safe to compare against in code and to use as a path parameter. The twenty ids run imix, ik, akbal, kan, chikchan, kimi, manik, lamat, muluk, ok, chuwen, eb, ben, ix, men, kib, kaban, etznab, kawak, ajaw.
`nameYucatec` required	string	Display name in the standard Maya orthography, where an ejective is written with a modifier letter rather than a typewriter quote. A proper noun carried as data, identical under every lang.
`nameClassic` required	string	The sixteenth century Yucatec spelling of the same sign, which is the form most printed reference tables and older books use.
`nameKiche` required	string	The Kʼicheʼ name from the living highland daykeeping tradition, which is the vocabulary a nawal reading in Guatemala uses. A parallel naming tradition rather than a translation, so it is identical under every lang.
`gloss` required	string	The short day-name association, translated in place because it is a common noun rather than a name. Two published readings of the twenty signs disagree on six of them, so the alternate reading ships beside this one rather than one being resolved away.
`glossAlternate` required	string	The glyph-table reading of the same sign, translated in place. On the six signs where the two readings disagree this is the one the composed prose follows, so a reading that seems to ignore the gloss above is doing so deliberately.
`direction` required	string	World direction this sign belongs to under the requested scheme: east, north, west or south. The twenty signs divide evenly into four groups of five, so exactly five signs share each quarter.
`color` required	string	Colour paired with the direction: red for east, white for north, black for west, yellow for south. Always English so it stays safe to key a palette off.
`keynote` required	string	The sign in one composed sentence: both names, what it is about and the glyph reading behind it.
`directionReading` required	string	The world direction in prose, followed by a line naming which of the two published readings produced it. The two sit one quarter turn apart on all twenty signs.
`essence` required	string	What the sign is about, as a clause rather than a sentence, because it is spliced into composed prose elsewhere in the API. Translated in place.
`strengths` required	array of string	What the sign does well, as full sentences rather than keywords.
`challenges` required	array of string	Where the same temperament costs the sign something. Each one is the shadow of a strength above rather than an unrelated flaw.

Show all fieldsShow fewer fields

Field	Type	Description
`guidance` required	string	The one thing worth doing differently under this sign.
`trecena` required	object	The thirteen day period this sign opens. Composed from the sign rather than stored, so the two can never disagree.
`trecena.number` required	number	The trecena this sign opens, 1 to 20. Every sign opens exactly one trecena, because 13 and 20 share no factor.
`trecena.reading` required	string	The composed reading of the thirteen day period this sign opens.
`conventions` required	object	The conventions this profile was served under.
`conventions.directionScheme` required	string	The direction reading actually applied. The two readings sit one quarter turn apart, so a direction stored without this value is ambiguous.

Example response

{
  "position": 1,
  "id": "imix",
  "nameYucatec": "Imix",
  "nameClassic": "Imix",
  "nameKiche": "IMOX",
  "gloss": "crocodile",
  "glossAlternate": "Naah Kan, the Primordial Snake; the essence of water",
  "direction": "north",
  "color": "white",
  "keynote": "The nawal Imix, called IMOX in the highland daykeeping tradition, is the first water, the unformed source every later shape is drawn out of. The sign itself is read as Naah Kan, the Primordial Snake; the essence of water.",
  "directionReading": "The sign faces north, the quarter of the ancestors and of everything overhead, and carries the colour white. Directions follow the codex reading, which is the one most reference tables print.",
  "essence": "the first water, the unformed source every later shape is drawn out of",
  "strengths": [
    "Begins things other people are still describing, and works comfortably before a shape exists"
  ],
  "challenges": [
    "Takes on more feeling than belongs to it and calls the weight its own"
  ],
  "guidance": "Give the day a container. Water without banks floods, and the same instinct that opens a thing can drown it.",
  "trecena": {
    "number": 1,
    "reading": "Trecena 1 opens on 1 Imix and runs for thirteen days under it. The whole period takes its colour from the first water, the unformed source every later shape is drawn out of."
  },
  "conventions": {
    "directionScheme": "madrid-codex"
  }
}

List the 20 Mayan trecenas - Tzolkin thirteen day period API

GET /api/v2/mesoamerican-astrology/mayan/trecenas

Retrieve all twenty trecenas, the thirteen day periods the 260 day Tzolkin divides into. Each entry returns the period number, the day sign it opens on in both naming traditions, and a composed reading of what the period carries. Built for calendar apps, energy period trackers and content planners that work in thirteen day blocks rather than in weeks.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.
`limit` query	integer	Maximum items to return per page. Range: 1-20, default 20. Default `20`.
`offset` query	integer	Number of items to skip for pagination. Default 0. Default `0`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/trecenas" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`total` required	number	Total trecenas in the round. Always 20, because 260 divided by 13 is exactly 20.
`limit` required	number	Maximum items returned for this page.
`offset` required	number	Number of items skipped before this page.
`trecenas` required	array of object	Trecenas for the current page, in order from the one that opens on 1 Imix.
`trecenas[].number` required	number	Which of the twenty thirteen day periods this is, 1 to 20. Trecena 1 opens on 1 Imix and the openers step thirteen signs at a time from there.
`trecenas[].rulingSign` required	string	Machine identifier of the day sign the period opens on, which the tradition reads as colouring all thirteen of its days.
`trecenas[].rulingSignName` required	string	Display name of the sign the period opens on. A proper noun carried as data.
`trecenas[].rulingSignKiche` required	string	Kʼicheʼ name of the same sign, the vocabulary a highland reading uses.
`trecenas[].length` required	number	Days in the period. Always 13, which is what the word trecena means.
`trecenas[].reading` required	string	The composed reading of the period, built from the sign it opens on. Composed rather than stored, so it can never drift away from the day sign it is drawn from.

Example response

{
  "total": 20,
  "limit": 20,
  "offset": 0,
  "trecenas": [
    {
      "number": 1,
      "rulingSign": "imix",
      "rulingSignName": "Imix",
      "rulingSignKiche": "IMOX",
      "length": 13,
      "reading": "Trecena 1 opens on 1 Imix and runs for thirteen days under it. The whole period takes its colour from the first water, the unformed source every later shape is drawn out of."
    }
  ]
}

Get one Mayan trecena - Thirteen day period profile API

GET /api/v2/mesoamerican-astrology/mayan/trecenas/{number}

Retrieve one of the twenty trecenas by number, with the day sign it opens on in both naming traditions and a composed reading of the period. Built for period detail pages and for apps that show which thirteen day block a date falls in.

Parameters

Parameter	Type	Description
`number` required path	integer	Trecena number, 1 to 20. Trecena 1 opens on 1 Imix, trecena 2 on 1 Ix, and each subsequent period opens thirteen signs further round the twenty.
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/trecenas/1" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`number` required	number	Which of the twenty thirteen day periods this is, 1 to 20. Trecena 1 opens on 1 Imix and the openers step thirteen signs at a time from there.
`rulingSign` required	string	Machine identifier of the day sign the period opens on, which the tradition reads as colouring all thirteen of its days.
`rulingSignName` required	string	Display name of the sign the period opens on. A proper noun carried as data.
`rulingSignKiche` required	string	Kʼicheʼ name of the same sign, the vocabulary a highland reading uses.
`length` required	number	Days in the period. Always 13, which is what the word trecena means.
`reading` required	string	The composed reading of the period, built from the sign it opens on. Composed rather than stored, so it can never drift away from the day sign it is drawn from.

Example response

{
  "number": 1,
  "rulingSign": "imix",
  "rulingSignName": "Imix",
  "rulingSignKiche": "IMOX",
  "length": 13,
  "reading": "Trecena 1 opens on 1 Imix and runs for thirteen days under it. The whole period takes its colour from the first water, the unformed source every later shape is drawn out of."
}

List the 19 Haab periods - Maya solar calendar month API

GET /api/v2/mesoamerican-astrology/mayan/haab-months

Retrieve all nineteen periods of the Haab, the 365 day Maya year: eighteen months of twenty days plus the five days of Wayebʼ. Each entry returns the machine id, both spellings of the name, the length, what the name means and a composed reading. Built for calendar reference pages and for any app that has to label a Haab date rather than only compute it.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.
`limit` query	integer	Maximum items to return per page. Range: 1-19, default 19. Default `19`.
`offset` query	integer	Number of items to skip for pagination. Default 0. Default `0`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/haab-months" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`total` required	number	Total periods in the Haab year. Always 19: eighteen months plus Wayebʼ, which is a period of the year even though it is only five days.
`limit` required	number	Maximum items returned for this page.
`offset` required	number	Number of items skipped before this page.
`months` required	array of object	Periods for the current page, in order from Pop.
`months[].position` required	number	Place in the Haab year, 1 to 19. Pop is 1 and Wayebʼ is 19, so a position of 19 always means the five short days.
`months[].id` required	string	Machine identifier of the Haab period, always lowercase ASCII, so it stays safe to compare against and to use as a path parameter. The nineteen ids run pop, wo, sip, sotz, sek, xul, yaxkin, mol, chen, yax, sak, keh, mak, kankin, muwan, pax, kayab, kumku, wayeb.
`months[].nameYucatec` required	string	Display name in the standard orthography. A proper noun carried as data, identical under every lang.
`months[].nameClassic` required	string	The sixteenth century Yucatec spelling, which is the form most printed tables use.
`months[].length` required	number	Days in the period. Twenty for the eighteen months and five for Wayebʼ, which is never twenty. Days inside a period are numbered from 0, so a twenty day period runs 0 to 19.
`months[].gloss` required	string	What the period name means, translated in place because it is a common noun rather than a name.
`months[].reading` required	string	The composed reading of the period, built from its position, its length and its gloss.

Example response

{
  "total": 19,
  "limit": 19,
  "offset": 0,
  "months": [
    {
      "position": 1,
      "id": "pop",
      "nameYucatec": "Pop",
      "nameClassic": "Pop",
      "length": 20,
      "gloss": "mat",
      "reading": "The Haab period Pop stands at position 1 in the year and runs 20 days. The mat is the seat of authority, so the year opens on who is entitled to speak and on the households the mat gathers."
    }
  ]
}

Get one Haab period - Maya solar calendar month profile API

GET /api/v2/mesoamerican-astrology/mayan/haab-months/{id}

Retrieve one of the nineteen Haab periods by id, with both spellings of its name, its position in the year, its length and a composed reading. Built for calendar detail pages and for labelling a Haab date a chart route has already returned.

Parameters

Parameter	Type	Description
`id` required path	string enum	Haab period id, case-insensitive and punctuation-insensitive. One of pop, wo, sip, sotz, sek, xul, yaxkin, mol, chen, yax, sak, keh, mak, kankin, muwan, pax, kayab, kumku, wayeb.
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/mayan/haab-months/pop" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`position` required	number	Place in the Haab year, 1 to 19. Pop is 1 and Wayebʼ is 19, so a position of 19 always means the five short days.
`id` required	string	Machine identifier of the Haab period, always lowercase ASCII, so it stays safe to compare against and to use as a path parameter. The nineteen ids run pop, wo, sip, sotz, sek, xul, yaxkin, mol, chen, yax, sak, keh, mak, kankin, muwan, pax, kayab, kumku, wayeb.
`nameYucatec` required	string	Display name in the standard orthography. A proper noun carried as data, identical under every lang.
`nameClassic` required	string	The sixteenth century Yucatec spelling, which is the form most printed tables use.
`length` required	number	Days in the period. Twenty for the eighteen months and five for Wayebʼ, which is never twenty. Days inside a period are numbered from 0, so a twenty day period runs 0 to 19.
`gloss` required	string	What the period name means, translated in place because it is a common noun rather than a name.
`reading` required	string	The composed reading of the period, built from its position, its length and its gloss.

Example response

{
  "position": 1,
  "id": "pop",
  "nameYucatec": "Pop",
  "nameClassic": "Pop",
  "length": 20,
  "gloss": "mat",
  "reading": "The Haab period Pop stands at position 1 in the year and runs 20 days. The mat is the seat of authority, so the year opens on who is entitled to speak and on the households the mat gathers."
}

Aztec day sign for a date - Tonalpohualli calculator API

POST /api/v2/mesoamerican-astrology/aztec/tonalpohualli

Aztec calendar day sign calculator: returns the tonalpohualli day sign, its coefficient 1 to 13 and its trecena for any Gregorian date, with a composed reading. The count is anchored on the recorded day of the fall of Tenochtitlan and runs in step with the Maya count under the default constant, verified on the anchor and on two modern dates. Built for Aztec calendar apps, Mexica day sign features and AI agents answering what is my Aztec sign.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

Request body

Field	Type	Description
`date` required	string (date)	Date in YYYY-MM-DD format, in the PROLEPTIC GREGORIAN calendar, extended backwards unchanged through the 1582 reform. Years 1 to 4000 are accepted. A reference converter that switches to the Julian calendar below the reform will disagree with a date before 15 October 1582 by ten or eleven days; that is a difference of input convention rather than of arithmetic, and passing the Julian equivalent to such a tool reproduces these values exactly. A single-digit month or day is accepted and zero padded.

curl

curl -X POST "https://roxyapi.com/api/v2/mesoamerican-astrology/aztec/tonalpohualli" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2012-12-21"}'

Response fields

Field	Type	Description
`daySign` required	string	Machine identifier of the tonalpohualli day sign, always lowercase ASCII Nahuatl whatever the lang parameter says, so it stays safe to compare against in code. The twenty ids run cipactli, ehecatl, calli, cuetzpalin, coatl, miquiztli, mazatl, tochtli, atl, itzcuintli, ozomahtli, malinalli, acatl, ocelotl, cuauhtli, cozcacuauhtli, ollin, tecpatl, quiahuitl, xochitl.
`daySignName` required	string	Display name in Nahuatl with the vowel length marks the reference tables print. A proper noun carried as data, so it is identical under every lang.
`gloss` required	string	What the sign name means, translated in place because it is a common noun. Several English renderings are in circulation for some signs and all of them are given rather than one being picked.
`direction` required	string	World direction the sign belongs to: east, north, west or south. The twenty run through the four quarters in order, so the direction is a property of the position as much as of the sign.
`number` required	number	The tonalpohualli coefficient, 1 to 13. Structurally the same count as the Maya coefficient and read the same way: a rank it is not.
`trecena` required	object	The thirteen day period this day belongs to, named by the sign it opens on. No patron deity is returned: the published patron column carries an unresolved disagreement on two of the twenty rows, and a column that is right for eighteen and guessed for two is worse than none.
`trecena.number` required	number	Which of the twenty thirteen day periods this day falls in, 1 to 20.
`trecena.dayOfTrecena` required	number	Position of this day inside its trecena, 1 to 13. Always equal to the coefficient.
`trecena.startSign` required	string	Machine identifier of the day sign the trecena opens on.
`trecena.startSignName` required	string	Display name of the sign the trecena opens on. A proper noun carried as data.
`keynote` required	string	The sign in one composed sentence. Composed per request from the sign components rather than stored whole.
`guidance` required	string	The one thing worth doing differently under this sign.
`scope` required	string	A plain statement of what this family covers and what it deliberately leaves out. Present on every response so nobody has to guess whether a missing field is an outage or a decision.
`date` required	string	Echo of the date the day was resolved from, in proleptic Gregorian.

Show all fieldsShow fewer fields

Field	Type	Description
`conventions` required	object	The conventions this answer was computed under, echoed so the result is self describing.
`conventions.correlation` required	string	The correlation this count runs on, anchored on the recorded day 1 Coatl at the fall of Tenochtitlan, 13 August 1521 in the Julian calendar and 23 August 1521 in the proleptic Gregorian calendar this API takes. It is echoed rather than requested because it is not a switch: the anchor is a civil date, so no correlation constant enters the arithmetic, and the published alternatives for this calendar move the solar year alignment rather than the day count. The count was verified to run in step with the Maya count under the default constant, on the anchor and on two modern dates.

Example response

{
  "daySign": "coatl",
  "daySignName": "Cōātl",
  "gloss": "serpent / snake",
  "direction": "east",
  "number": 1,
  "trecena": {
    "number": 9,
    "dayOfTrecena": 1,
    "startSign": "coatl",
    "startSignName": "Cōātl"
  },
  "keynote": "The tonalpohualli sign Cōātl is the serpent, the charge that runs the whole length of a living thing. It is read as serpent / snake, and it belongs to the east.",
  "guidance": "Move what has built up in the body before it picks its own target.",
  "scope": "This count returns the day sign, its coefficient and its trecena. The night lord and the solar year are not returned, because the sources consulted for them do not agree closely enough to publish.",
  "date": "1521-08-23",
  "conventions": {
    "correlation": "caso"
  }
}

Daily Aztec energy reading - Tonalpohualli day sign of the day API

GET /api/v2/mesoamerican-astrology/aztec/daily

Aztec energy of the day: the tonalpohualli day sign, its coefficient and its trecena for today or for any date you name, with a composed reading. Content is fixed for a given date and rolls over at midnight UTC, so a daily feed can cache it safely and an editorial calendar can be filled weeks ahead. Built for daily energy widgets, Mexica day sign feeds and chatbot answers about what today carries.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.
`date` query	string (date)	Date in YYYY-MM-DD format, in the PROLEPTIC GREGORIAN calendar, extended backwards unchanged through the 1582 reform. Years 1 to 4000 are accepted. A reference converter that switches to the Julian calendar below the reform will disagree with a date before 15 October 1582 by ten or eleven days; that is a difference of input convention rather than of arithmetic, and passing the Julian equivalent to such a tool reproduces these values exactly. A single-digit month or day is accepted and zero padded. Defaults to the current day in UTC.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/aztec/daily" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`daySign` required	string	Machine identifier of the tonalpohualli day sign, always lowercase ASCII Nahuatl whatever the lang parameter says, so it stays safe to compare against in code. The twenty ids run cipactli, ehecatl, calli, cuetzpalin, coatl, miquiztli, mazatl, tochtli, atl, itzcuintli, ozomahtli, malinalli, acatl, ocelotl, cuauhtli, cozcacuauhtli, ollin, tecpatl, quiahuitl, xochitl.
`daySignName` required	string	Display name in Nahuatl with the vowel length marks the reference tables print. A proper noun carried as data, so it is identical under every lang.
`gloss` required	string	What the sign name means, translated in place because it is a common noun. Several English renderings are in circulation for some signs and all of them are given rather than one being picked.
`direction` required	string	World direction the sign belongs to: east, north, west or south. The twenty run through the four quarters in order, so the direction is a property of the position as much as of the sign.
`number` required	number	The tonalpohualli coefficient, 1 to 13. Structurally the same count as the Maya coefficient and read the same way: a rank it is not.
`trecena` required	object	The thirteen day period this day belongs to, named by the sign it opens on. No patron deity is returned: the published patron column carries an unresolved disagreement on two of the twenty rows, and a column that is right for eighteen and guessed for two is worse than none.
`trecena.number` required	number	Which of the twenty thirteen day periods this day falls in, 1 to 20.
`trecena.dayOfTrecena` required	number	Position of this day inside its trecena, 1 to 13. Always equal to the coefficient.
`trecena.startSign` required	string	Machine identifier of the day sign the trecena opens on.
`trecena.startSignName` required	string	Display name of the sign the trecena opens on. A proper noun carried as data.
`keynote` required	string	The sign in one composed sentence. Composed per request from the sign components rather than stored whole.
`guidance` required	string	The one thing worth doing differently under this sign.
`scope` required	string	A plain statement of what this family covers and what it deliberately leaves out. Present on every response so nobody has to guess whether a missing field is an outage or a decision.
`date` required	string	Date of this reading. Echoes the date requested, or the current day in UTC when it was omitted.

Show all fieldsShow fewer fields

Field	Type	Description
`overview` required	string	What the day carries, placing it inside its trecena as well as naming it. Composed per request, so it stays consistent with the keynote rather than being a second opinion.
`conventions` required	object	The conventions this reading was computed under, echoed so the result is self describing.
`conventions.correlation` required	string	The correlation this count runs on, anchored on the recorded day 1 Coatl at the fall of Tenochtitlan, 13 August 1521 in the Julian calendar and 23 August 1521 in the proleptic Gregorian calendar this API takes. It is echoed rather than requested because it is not a switch: the anchor is a civil date, so no correlation constant enters the arithmetic, and the published alternatives for this calendar move the solar year alignment rather than the day count. The count was verified to run in step with the Maya count under the default constant, on the anchor and on two modern dates.

Example response

{
  "daySign": "coatl",
  "daySignName": "Cōātl",
  "gloss": "serpent / snake",
  "direction": "east",
  "number": 1,
  "trecena": {
    "number": 9,
    "dayOfTrecena": 1,
    "startSign": "coatl",
    "startSignName": "Cōātl"
  },
  "keynote": "The tonalpohualli sign Cōātl is the serpent, the charge that runs the whole length of a living thing. It is read as serpent / snake, and it belongs to the east.",
  "guidance": "Move what has built up in the body before it picks its own target.",
  "scope": "This count returns the day sign, its coefficient and its trecena. The night lord and the solar year are not returned, because the sources consulted for them do not agree closely enough to publish.",
  "date": "2026-09-02",
  "overview": "Today is 2 Calli in the tonalpohualli, day 2 of the trecena that opened on 1 Ehēcatl. The day is coloured by the house, the enclosure that makes rest and privacy possible.",
  "conventions": {
    "correlation": "caso"
  }
}

List the 20 Aztec day signs - Tonalpohualli sign catalogue API

GET /api/v2/mesoamerican-astrology/aztec/day-signs

Retrieve all twenty tonalpohualli day signs in sequence order from Cipactli to Xochitl. Each entry returns the machine id, the Nahuatl name, what it means, the world direction it belongs to and a composed reading. Built for Aztec sign pickers, Mexica calendar reference pages and any app that needs the whole set in one call.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.
`limit` query	integer	Maximum items to return per page. Range: 1-20, default 20. Default `20`.
`offset` query	integer	Number of items to skip for pagination. Default 0. Default `0`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/aztec/day-signs" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`total` required	number	Total signs in the cycle. Always 20; the sign set is closed.
`limit` required	number	Maximum items returned for this page.
`offset` required	number	Number of items skipped before this page.
`daySigns` required	array of object	Day signs for the current page, in sequence order.
`daySigns[].position` required	number	Place in the twenty sign sequence, 1 to 20, counting Cipactli as 1. The sequence never varies and is what the trecenas are indexed against.
`daySigns[].id` required	string	Machine identifier of the day sign, always lowercase ASCII Nahuatl whatever the lang parameter says, so it stays safe to compare against and to use as a path parameter. The twenty ids run cipactli, ehecatl, calli, cuetzpalin, coatl, miquiztli, mazatl, tochtli, atl, itzcuintli, ozomahtli, malinalli, acatl, ocelotl, cuauhtli, cozcacuauhtli, ollin, tecpatl, quiahuitl, xochitl.
`daySigns[].nameNahuatl` required	string	Display name in Nahuatl with the vowel length marks the reference tables print. A proper noun carried as data, identical under every lang.
`daySigns[].gloss` required	string	What the sign name means, translated in place because it is a common noun. Where several English renderings are in circulation all of them are given rather than one being picked.
`daySigns[].direction` required	string	World direction the sign belongs to: east, north, west or south. The twenty run through the four quarters in strict rotation, so every fourth sign shares a quarter.
`daySigns[].essence` required	string	What the sign is about, as a clause rather than a sentence, because it is spliced into composed prose elsewhere in the API. Translated in place.
`daySigns[].guidance` required	string	The one thing worth doing differently under this sign.
`daySigns[].keynote` required	string	The sign in one composed sentence, built from the components above.

Example response

{
  "total": 20,
  "limit": 20,
  "offset": 0,
  "daySigns": [
    {
      "position": 1,
      "id": "cipactli",
      "nameNahuatl": "Cipactli",
      "gloss": "crocodile / alligator / caiman",
      "direction": "east",
      "essence": "the crocodile in the first water, the ground the world was built on",
      "guidance": "Begin something, and give it a base wide enough to carry the rest.",
      "keynote": "The tonalpohualli sign Cipactli is the crocodile in the first water, the ground the world was built on. It is read as crocodile / alligator / caiman, and it belongs to the east."
    }
  ]
}

Get one Aztec day sign - Tonalpohualli sign profile API

GET /api/v2/mesoamerican-astrology/aztec/day-signs/{id}

Retrieve the full profile of one tonalpohualli day sign: the Nahuatl name, what it means, the world direction it belongs to, a composed keynote and one line of guidance. Built for Aztec sign detail pages, day sign cards and chatbot answers about a single Mexica sign.

Parameters

Parameter	Type	Description
`id` required path	string enum	Day sign id, case-insensitive and punctuation-insensitive. One of cipactli, ehecatl, calli, cuetzpalin, coatl, miquiztli, mazatl, tochtli, atl, itzcuintli, ozomahtli, malinalli, acatl, ocelotl, cuauhtli, cozcacuauhtli, ollin, tecpatl, quiahuitl, xochitl.
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/aztec/day-signs/cipactli" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`position` required	number	Place in the twenty sign sequence, 1 to 20, counting Cipactli as 1. The sequence never varies and is what the trecenas are indexed against.
`id` required	string	Machine identifier of the day sign, always lowercase ASCII Nahuatl whatever the lang parameter says, so it stays safe to compare against and to use as a path parameter. The twenty ids run cipactli, ehecatl, calli, cuetzpalin, coatl, miquiztli, mazatl, tochtli, atl, itzcuintli, ozomahtli, malinalli, acatl, ocelotl, cuauhtli, cozcacuauhtli, ollin, tecpatl, quiahuitl, xochitl.
`nameNahuatl` required	string	Display name in Nahuatl with the vowel length marks the reference tables print. A proper noun carried as data, identical under every lang.
`gloss` required	string	What the sign name means, translated in place because it is a common noun. Where several English renderings are in circulation all of them are given rather than one being picked.
`direction` required	string	World direction the sign belongs to: east, north, west or south. The twenty run through the four quarters in strict rotation, so every fourth sign shares a quarter.
`essence` required	string	What the sign is about, as a clause rather than a sentence, because it is spliced into composed prose elsewhere in the API. Translated in place.
`guidance` required	string	The one thing worth doing differently under this sign.
`keynote` required	string	The sign in one composed sentence, built from the components above.

Example response

{
  "position": 1,
  "id": "cipactli",
  "nameNahuatl": "Cipactli",
  "gloss": "crocodile / alligator / caiman",
  "direction": "east",
  "essence": "the crocodile in the first water, the ground the world was built on",
  "guidance": "Begin something, and give it a base wide enough to carry the rest.",
  "keynote": "The tonalpohualli sign Cipactli is the crocodile in the first water, the ground the world was built on. It is read as crocodile / alligator / caiman, and it belongs to the east."
}

List the 20 Aztec trecenas - Tonalpohualli thirteen day period API

GET /api/v2/mesoamerican-astrology/aztec/trecenas

Retrieve all twenty trecenas, the thirteen day periods the 260 day tonalpohualli divides into. Each entry returns the period number, the day sign it opens on and a composed reading of what the period carries. Built for Aztec calendar apps, energy period trackers and content planners that work in thirteen day blocks.

Parameters

Parameter	Type	Description
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.
`limit` query	integer	Maximum items to return per page. Range: 1-20, default 20. Default `20`.
`offset` query	integer	Number of items to skip for pagination. Default 0. Default `0`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/aztec/trecenas" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`total` required	number	Total trecenas in the count. Always 20, because 260 divided by 13 is exactly 20.
`limit` required	number	Maximum items returned for this page.
`offset` required	number	Number of items skipped before this page.
`trecenas` required	array of object	Trecenas for the current page, in order from the one that opens on 1 Cipactli.
`trecenas[].number` required	number	Which of the twenty thirteen day periods this is, 1 to 20. Trecena 1 opens on 1 Cipactli and the openers step thirteen signs at a time from there.
`trecenas[].startSign` required	string	Machine identifier of the day sign the period opens on.
`trecenas[].startSignName` required	string	Display name of the sign the period opens on. A proper noun carried as data.
`trecenas[].length` required	number	Days in the period. Always 13, which is what the word trecena means.
`trecenas[].reading` required	string	The composed reading of the period, built from the sign it opens on rather than stored, so the two can never drift apart. No patron deity is named, because two of the twenty published patrons are disputed and none ships rather than eighteen shipping beside two guesses.

Example response

{
  "total": 20,
  "limit": 20,
  "offset": 0,
  "trecenas": [
    {
      "number": 1,
      "startSign": "cipactli",
      "startSignName": "Cipactli",
      "length": 13,
      "reading": "Trecena 1 opens on 1 Cipactli and runs for thirteen days under it. The period takes its character from the crocodile in the first water, the ground the world was built on."
    }
  ]
}

Get one Aztec trecena - Tonalpohualli period profile API

GET /api/v2/mesoamerican-astrology/aztec/trecenas/{number}

Retrieve one of the twenty tonalpohualli trecenas by number, with the day sign it opens on and a composed reading of the period. Built for period detail pages and for apps that show which thirteen day block a date falls in.

Parameters

Parameter	Type	Description
`number` required path	integer	Trecena number, 1 to 20. Trecena 1 opens on 1 Cipactli, trecena 2 on 1 Ocelotl, and each subsequent period opens thirteen signs further round the twenty.
`lang` query	string enum	Response language (BCP 47). Supported: en, tr, de, es, hi, pt, fr, ru, zh-Hans, zh-Hant. Defaults to en. Coverage varies by domain, and a field with no translation in the requested language returns English. Default `en`.

curl

curl "https://roxyapi.com/api/v2/mesoamerican-astrology/aztec/trecenas/1" \
  -H "X-API-Key: YOUR_KEY"

Response fields

Field	Type	Description
`number` required	number	Which of the twenty thirteen day periods this is, 1 to 20. Trecena 1 opens on 1 Cipactli and the openers step thirteen signs at a time from there.
`startSign` required	string	Machine identifier of the day sign the period opens on.
`startSignName` required	string	Display name of the sign the period opens on. A proper noun carried as data.
`length` required	number	Days in the period. Always 13, which is what the word trecena means.
`reading` required	string	The composed reading of the period, built from the sign it opens on rather than stored, so the two can never drift apart. No patron deity is named, because two of the twenty published patrons are disputed and none ships rather than eighteen shipping beside two guesses.

Example response

{
  "number": 1,
  "startSign": "cipactli",
  "startSignName": "Cipactli",
  "length": 13,
  "reading": "Trecena 1 opens on 1 Cipactli and runs for thirteen days under it. The period takes its character from the crocodile in the first water, the ground the world was built on."
}