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.
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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.calculate_tzolkin(date='2012-12-21')
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->calculateTzolkin(date: '2012-12-21');
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.Tzolkin.PostAsync(new() { /* request fields above */ });
Typed SDKs in 6 languages. On Remote MCP this is the tool post_mesoamerican_astrology_mayan_tzolkin on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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 optional
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.
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 optional
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
200 OK
{
"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"
}
}
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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.generate_mayan_chart(date='2012-12-21')
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->generateMayanChart(date: '2012-12-21');
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.Chart.PostAsync(new() { /* request fields above */ });
Typed SDKs in 6 languages. On Remote MCP this is the tool post_mesoamerican_astrology_mayan_chart on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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 optional
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 optional
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.
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 optional
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
200 OK
{
"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"
}
}
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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.convert_long_count(date='2012-12-21', long_count='13.0.0.0.0', correlation='gmt-584283')
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->convertLongCount(date: '2012-12-21', longCount: '13.0.0.0.0', correlation: 'gmt-584283');
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.LongCount.Convert.PostAsync(new() { /* request fields above */ });
Typed SDKs in 6 languages. On Remote MCP this is the tool post_mesoamerican_astrology_mayan_long_count_convert on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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 optional
string (date)
Proleptic Gregorian date to convert INTO a Long Count. Supply this or longCount, never both and never neither.
longCount optional
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 optional
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.
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 optional
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
200 OK
{
"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"
}
}
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.
Call it
TypeScript
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.mesoamericanAstrology.getDailyMayanReading()
Install: npm install @roxyapi/sdk
Python
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.get_daily_mayan_reading()
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->getDailyMayanReading();
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.Daily.GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_mayan_daily on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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, optional
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, optional
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.
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 optional
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
200 OK
{
"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"
}
}
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.
Call it
TypeScript
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.mesoamericanAstrology.getMonthlyTzolkinCalendar()
Install: npm install @roxyapi/sdk
Python
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.get_monthly_tzolkin_calendar()
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->getMonthlyTzolkinCalendar();
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.Calendar.Monthly.GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_mayan_calendar_monthly on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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, optional
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, optional
integer
Calendar month of the grid, 1 to 12. Defaults to the current month in UTC.
correlation query, optional
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.
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.
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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.calculate_mayan_compatibility(person_a={'date': '2012-12-21'}, person_b={'date': '2012-12-21'})
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->calculateMayanCompatibility(personA: ['date' => '2012-12-21'], personB: ['date' => '2012-12-21']);
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.Compatibility.PostAsync(new() { /* request fields above */ });
Typed SDKs in 6 languages. On Remote MCP this is the tool post_mesoamerican_astrology_mayan_compatibility on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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 optional
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 optional
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.
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 optional
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
200 OK
{
"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"
}
}
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.
Call it
TypeScript
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.mesoamericanAstrology.listMayanDaySigns()
Install: npm install @roxyapi/sdk
Python
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.list_mayan_day_signs()
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->listMayanDaySigns();
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.DaySigns.GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_mayan_day_signs on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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, optional
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, optional
integer
Maximum items to return per page. Range: 1-20, default 20. Default 20.
offset query, optional
integer
Number of items to skip for pagination. Default 0. Default 0.
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.
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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.get_mayan_day_sign(id='imix')
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->getMayanDaySign(id: 'imix');
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.DaySigns["imix"].GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_mayan_day_signs_id on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
id path, required
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, optional
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, optional
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.
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
200 OK
{
"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"
}
}
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.
Call it
TypeScript
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.mesoamericanAstrology.listTrecenas()
Install: npm install @roxyapi/sdk
Python
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.list_trecenas()
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->listTrecenas();
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.Trecenas.GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_mayan_trecenas on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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, optional
integer
Maximum items to return per page. Range: 1-20, default 20. Default 20.
offset query, optional
integer
Number of items to skip for pagination. Default 0. Default 0.
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
200 OK
{
"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."
}
]
}
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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.get_trecena(number=1)
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->getTrecena(number: 1);
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.Trecenas["1"].GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_mayan_trecenas_number on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
number path, required
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, optional
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.
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
200 OK
{
"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."
}
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.
Call it
TypeScript
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.mesoamericanAstrology.listHaabMonths()
Install: npm install @roxyapi/sdk
Python
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.list_haab_months()
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->listHaabMonths();
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.HaabMonths.GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_mayan_haab_months on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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, optional
integer
Maximum items to return per page. Range: 1-19, default 19. Default 19.
offset query, optional
integer
Number of items to skip for pagination. Default 0. Default 0.
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
200 OK
{
"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."
}
]
}
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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.get_haab_month(id='pop')
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->getHaabMonth(id: 'pop');
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Mayan.HaabMonths["pop"].GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_mayan_haab_months_id on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
id path, required
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, optional
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.
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
200 OK
{
"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 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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.calculate_tonalpohualli(date='2012-12-21')
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->calculateTonalpohualli(date: '2012-12-21');
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Aztec.Tonalpohualli.PostAsync(new() { /* request fields above */ });
Typed SDKs in 6 languages. On Remote MCP this is the tool post_mesoamerican_astrology_aztec_tonalpohualli on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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.
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
200 OK
{
"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"
}
}
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.
Call it
TypeScript
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.mesoamericanAstrology.getDailyAztecReading()
Install: npm install @roxyapi/sdk
Python
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.get_daily_aztec_reading()
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->getDailyAztecReading();
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Aztec.Daily.GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_aztec_daily on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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, optional
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.
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
200 OK
{
"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"
}
}
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.
Call it
TypeScript
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.mesoamericanAstrology.listAztecDaySigns()
Install: npm install @roxyapi/sdk
Python
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.list_aztec_day_signs()
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->listAztecDaySigns();
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Aztec.DaySigns.GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_aztec_day_signs on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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, optional
integer
Maximum items to return per page. Range: 1-20, default 20. Default 20.
offset query, optional
integer
Number of items to skip for pagination. Default 0. Default 0.
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
200 OK
{
"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."
}
]
}
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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.get_aztec_day_sign(id='cipactli')
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->getAztecDaySign(id: 'cipactli');
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Aztec.DaySigns["cipactli"].GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_aztec_day_signs_id on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
id path, required
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, optional
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.
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
200 OK
{
"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."
}
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.
Call it
TypeScript
import { createRoxy } from '@roxyapi/sdk'
const roxy = createRoxy(process.env.ROXY_API_KEY!)
const { data } = await roxy.mesoamericanAstrology.listAztecTrecenas()
Install: npm install @roxyapi/sdk
Python
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.list_aztec_trecenas()
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->listAztecTrecenas();
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Aztec.Trecenas.GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_aztec_trecenas on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
lang query, optional
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, optional
integer
Maximum items to return per page. Range: 1-20, default 20. Default 20.
offset query, optional
integer
Number of items to skip for pagination. Default 0. Default 0.
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
200 OK
{
"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."
}
]
}
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.
from roxy_sdk import create_roxy
roxy = create_roxy("YOUR_API_KEY")
result = roxy.mesoamerican_astrology.get_aztec_trecena(number=1)
Install: pip install roxy-sdk
PHP
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->mesoamericanAstrology->getAztecTrecena(number: 1);
Install: composer require roxyapi/sdk
C#
using RoxyApi;
var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!);
var result = await roxy.MesoamericanAstrology.Aztec.Trecenas["1"].GetAsync();
Typed SDKs in 6 languages. On Remote MCP this is the tool get_mesoamerican_astrology_aztec_trecenas_number on the Mesoamerican Astrology server, https://roxyapi.com/mcp/mesoamerican-astrology.
Parameters
Parameter
Type
Description
number path, required
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, optional
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.
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
200 OK
{
"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."
}
R
RosieYour AI guide to RoxyAPI
R
Hi, I am Rosie, your guide to the RoxyAPI insight tools.
Ask me to read your birth chart, pull a card, or map your numbers, and I will interpret what it means for you. Unlike most AIs, I never make the numbers up: every reading runs on real, verified calculations. Curious about the API, pricing, or docs instead? Ask me that too.
