# Mesoamerican Astrology API > Calculate Mayan astrology day signs, the Tzolkin sacred round, the Haab year, the full Long Count and the Aztec tonalpohualli from any date: day sign and coefficient, trecena, Calendar Round, Lord of the Night, Year Bearer and the five point Cruz Maya, each with a composed reading. The correlation constant that makes two Mayan calculators disagree is a typed parameter with a named default rather than a hidden pick, and every response echoes the conventions it was computed under, so a saved chart stays reproducible. Both naming traditions ship on every sign, the Yucatec spelling and the Kʼicheʼ name daykeepers actually use, and readings come back in every language the API ships. One key covers every RoxyAPI domain, with Remote MCP and typed SDKs. A Mayan day sign that tells you which correlation it came from. - Product page: https://roxyapi.com/products/mesoamerican-astrology-api - OpenAPI spec: https://roxyapi.com/api/v2/mesoamerican-astrology/openapi.json - Remote MCP server: https://roxyapi.com/mcp/mesoamerican-astrology - Authentication: `X-API-Key` header on every request - Pricing: https://roxyapi.com/pricing (all domains included in every plan) ## Stats - uptime: 99.95%+ - endpoints: 18 ## Features - The correlation constant is a typed request parameter with a named default, not a hidden pick: four published constants are offered, the resolved one comes back on every response, and a saved chart can therefore be reproduced or matched against a published inscription reading years later - Both naming traditions on every day sign: the Yucatec spelling in the standard orthography, the sixteenth century form that printed reference tables use, and the Kʼicheʼ name from the living highland daykeeping practice, all carried as data so they read the same in every language - One call returns the whole day rather than a fragment of it: Tzolkin sign and coefficient, Haab date, the five position Long Count with its day count and Julian Day Number, the Calendar Round, the Lord of the Night, the Year Bearer and the five point Cruz Maya - The Year Bearer school and the world direction reading are typed conventions too, because the three bearer sets share no member and the two direction readings sit a quarter turn apart, so a silent default would be a school choice disguised as a fact - The Aztec tonalpohualli is a first class family on the same key, with its own anchored day count, sign catalogue and trecenas, and it states plainly which fields it does not return and why - Any date from 3114 BC to the twenty second century costs exactly what today costs, because a Mesoamerican day is an integer function of the elapsed day rather than an ephemeris lookup, so a date five millennia back costs exactly what today costs - Classical and academic count only: the unbroken day count from the Long Count epoch, verified against two institutional converters at thirteen dates spanning five millennia and under every correlation offered, so an answer here is one a daykeeper would recognise ## Includes The Mesoamerican Astrology API bundles these sub-APIs under one key: - Mayan Astrology API - Tzolkin API - Long Count Calendar API - Aztec Calendar API - Nahual Compatibility API ## Use Cases - Mayan astrology and nawal apps: day sign, coefficient, trecena and the five point cross from one birth date - Spanish language calculators: the nahual, the Cruz Maya and the daily energy, with the correlation daykeepers use - Calendar and education tools: Long Count conversion both ways, Calendar Round, Haab dates and a whole month grid in one call - Daily content platforms: a deterministic day sign of the day for both calendars, cached and safe to schedule weeks ahead - Multi domain spiritual companions: a Mayan card beside a natal chart and a BaZi chart, on one key with the same conventions echo shape - Epigraphy and museum software: place an inscription date on a civil calendar under a named correlation constant ## FAQ ### How do I find my Mayan sign with an API? Send a birth date to the Tzolkin endpoint and the day sign comes back with its coefficient, its trecena and a composed nawal reading, in one response. The sign arrives in three namings at once: the standard Yucatec spelling, the sixteenth century form older books print, and the Kʼicheʼ name highland daykeepers use, so you can label it the way your audience expects. Typed SDKs and a Remote MCP server are available on the same key, along with every other RoxyAPI domain. ### Why do two Mayan sign calculators give different answers for one date? Usually one of two reasons, and both are stated on every response here. The first is the correlation constant, the number that ties the day count to a civil date: several are published, they sit a few days apart, and a calculator that does not say which it used cannot be checked. The second is that some popular tools run the modern Dreamspell or thirteen moon count, which freezes its count on 29 February and has therefore drifted away from the classical day count by a different amount at every date. This API runs the classical count only and names the constant it used. ### Which correlation constant should I use? Use the default unless you have a reason not to. It is the commonly accepted constant, the one the major institutional converter runs on, and the one a highland daykeeper count agrees with. The three alternatives are offered because published inscription readings sometimes use them and a researcher needs to reproduce a printed value; each shifts the Long Count by exactly its difference in days from the default, which makes a disagreement easy to diagnose rather than mysterious. ### What is the difference between the Mayan and the Aztec calendar here? They are two 260 day counts with the same structure, thirteen coefficients running against twenty day signs, under different names and different anchors. The Maya family returns the Tzolkin plus the Haab year, the Long Count and the Lord of the Night; the Aztec family returns the tonalpohualli day sign, its coefficient and its trecena. The Aztec side deliberately returns fewer fields, and every response says which ones and why: where the reference sources disagree, nothing ships rather than a guess. ### How is the Cruz Maya read? The cross has five points around the birth nawal: conception eight days before the birth day, destiny eight days after, and two arms six days after and six days before. Each point returns its own day sign and coefficient with a line on what it is read as. This is a living daykeeper convention rather than an archaeological reconstruction, and the response says so on the field itself, because the academic literature describes the day count and the year bearers but not a five point cross. ### Does it work for historical dates? Yes, and without losing accuracy, because a Mesoamerican day is a plain count of elapsed days rather than an astronomical lookup. Dates are read as proleptic Gregorian throughout, including before the 1582 reform, so a tool that switches to the Julian calendar below the reform will differ by ten or eleven days on the same input; the conversion endpoint flags any date before the reform for exactly that reason. Long Count conversion runs in both directions, so an inscription date can be placed on a civil calendar and back. ## Endpoints - `POST /api/v2/mesoamerican-astrology/mayan/tzolkin` Mayan day sign for a date - Tzolkin calculator API - `POST /api/v2/mesoamerican-astrology/mayan/chart` Generate a Mayan chart - Tzolkin, Haab and Long Count calculator API - `POST /api/v2/mesoamerican-astrology/mayan/long-count/convert` Convert a Maya Long Count - Long Count calendar converter API - `GET /api/v2/mesoamerican-astrology/mayan/daily` Daily Mayan energy reading - Tzolkin day sign of the day API - `GET /api/v2/mesoamerican-astrology/mayan/calendar/monthly` Monthly Tzolkin calendar grid - Maya calendar month API - `POST /api/v2/mesoamerican-astrology/mayan/compatibility` Mayan nawal compatibility - Tzolkin pair analysis API - `GET /api/v2/mesoamerican-astrology/mayan/day-signs` List the 20 Mayan day signs - Tzolkin nawal catalogue API - `GET /api/v2/mesoamerican-astrology/mayan/day-signs/{id}` Get one Mayan day sign - Nawal profile API - `GET /api/v2/mesoamerican-astrology/mayan/trecenas` List the 20 Mayan trecenas - Tzolkin thirteen day period API - `GET /api/v2/mesoamerican-astrology/mayan/trecenas/{number}` Get one Mayan trecena - Thirteen day period profile API - `GET /api/v2/mesoamerican-astrology/mayan/haab-months` List the 19 Haab periods - Maya solar calendar month API - `GET /api/v2/mesoamerican-astrology/mayan/haab-months/{id}` Get one Haab period - Maya solar calendar month profile API - `POST /api/v2/mesoamerican-astrology/aztec/tonalpohualli` Aztec day sign for a date - Tonalpohualli calculator API - `GET /api/v2/mesoamerican-astrology/aztec/daily` Daily Aztec energy reading - Tonalpohualli day sign of the day API - `GET /api/v2/mesoamerican-astrology/aztec/day-signs` List the 20 Aztec day signs - Tonalpohualli sign catalogue API - `GET /api/v2/mesoamerican-astrology/aztec/day-signs/{id}` Get one Aztec day sign - Tonalpohualli sign profile API - `GET /api/v2/mesoamerican-astrology/aztec/trecenas` List the 20 Aztec trecenas - Tonalpohualli thirteen day period API - `GET /api/v2/mesoamerican-astrology/aztec/trecenas/{number}` Get one Aztec trecena - Tonalpohualli period profile API ### Mesoamerican Astrology (`/mesoamerican-astrology/`) The lightest input in the catalog alongside feng shui: every route takes a birth `date` in `YYYY-MM-DD` and nothing else, no birth time, no coordinates, no timezone, no `/location/search` step. Dates are read as proleptic Gregorian throughout, including before the 1582 reform, so a converter that switches to the Julian calendar there will differ by ten or eleven days. Three school splits are typed request fields with named defaults: `correlation` on every Maya route, `yearBearerSystem` on the chart, `directionScheme` on compatibility and the sign catalogue. Whichever was used comes back under `conventions` on every response, which is the field to echo when a user says another site disagrees. - `POST /mesoamerican-astrology/mayan/tzolkin`: Mayan day sign from a birth date, with coefficient, trecena and a composed nawal reading. The sign arrives in three namings: `daySign` (canonical id, never translated), `daySignName`, `daySignClassic` and `daySignKiche`. - `POST /mesoamerican-astrology/mayan/chart`: The whole day in one call. Tzolkin, Haab, the five position `longCount` with `daysSinceEpoch` and `julianDayNumber`, `calendarRound`, `lordOfNight`, `yearBearer`, the five point Cruz Maya and a `summary`. - `POST /mesoamerican-astrology/mayan/long-count/convert`: Long Count to civil date or back. Send exactly one of `date` or `longCount`; both or neither returns 400. Pre-1582 dates come back with a `note` explaining the proleptic Gregorian reading. - `GET /mesoamerican-astrology/mayan/daily`: Day sign of the day plus an `overview` naming the trecena. Optional `date`, cached to the UTC rollover, so a content schedule built weeks ahead matches what ships. - `GET /mesoamerican-astrology/mayan/calendar/monthly`: Every civil day of a `year` and `month` with its day sign, number, trecena, `haab` string and `longCount`. One call fills a calendar UI. - `POST /mesoamerican-astrology/mayan/compatibility`: Two dates in, both days plus `daysApart`, five weighted `components` with `holds`, a composite `score`, a `verdict` band and a `summary`. The score is a RoxyAPI composite with a floor of 45, so render the components rather than the number alone. - `GET /mesoamerican-astrology/mayan/day-signs` and `/{id}`: The twenty signs. The list carries both glosses, `direction` and `color`; the single call adds the full reading and the trecena the sign opens. - `GET /mesoamerican-astrology/mayan/trecenas` and `/{number}`: The twenty thirteen day periods, each composed from the sign it opens on. - `GET /mesoamerican-astrology/mayan/haab-months` and `/{id}`: The nineteen Haab periods, eighteen of twenty days plus Wayebʼ of five. - `POST /mesoamerican-astrology/aztec/tonalpohualli`: The Aztec 260 day count. Same structure as the Tzolkin under Nahuatl names and a different anchor. Takes no `correlation` field and echoes its own anchor instead. - `GET /mesoamerican-astrology/aztec/daily`: Tonalpohualli sign of the day, same shape and same UTC rollover as the Maya daily. - `GET /mesoamerican-astrology/aztec/day-signs` and `/{id}`, `GET /mesoamerican-astrology/aztec/trecenas` and `/{number}`: The matching Aztec catalogues. Two response conventions worth knowing before you parse: `numberBand` is ABSENT rather than null for coefficients 4, 5, 6 and 10, because only nine of the thirteen have a character recorded, and the Aztec responses carry a `scope` sentence naming the fields that domain deliberately does not return. ## Example Response ``` POST /api/v2/mesoamerican-astrology/mayan/chart ``` ```json { "date": "2012-12-21", "tzolkin": { "daySign": "ajaw", "daySignName": "Ajaw", "daySignClassic": "Ahau", "daySignKiche": "AJPUʼ", "number": 4, "trecena": { "number": 13, "dayOfTrecena": 4, "rulingSign": "kaban", "rulingSignName": "Kabʼan" }, "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.", "strengths": [ "Finishes what was started and lets the result be seen", "Warms a whole room rather than one corner of it" ], "challenges": [ "Needs the light on it and dims when the light moves", "Treats a finished thing as final and stops asking about it" ], "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": 1, "reading": "The Haab year is carried by 1 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": "center", "offsetDays": 0, "daySign": "ajaw", "daySignName": "Ajaw", "daySignKiche": "AJPUʼ", "number": 4, "reading": "The centre of the cross is the birth nawal itself, 4 Ajaw, and every arm is read against it." }, { "position": "conception", "offsetDays": -8, "daySign": "eb", "daySignName": "Ebʼ", "daySignKiche": "E", "number": 9, "reading": "The conception arm, eight days before the birth day, is 9 Ebʼ. It is read as the root the life is drawn from." }, { "position": "destiny", "offsetDays": 8, "daySign": "lamat", "daySignName": "Lamat", "daySignKiche": "QʼANIL", "number": 12, "reading": "The destiny arm, eight days after the birth day, is 12 Lamat. It is read as later life and as what is left behind." }, { "position": "left", "offsetDays": 6, "daySign": "kimi", "daySignName": "Kimi", "daySignKiche": "KAME", "number": 10, "reading": "The left arm, six days after the birth day, is 10 Kimi. It is read as one of the two sides the life is balanced between." }, { "position": "right", "offsetDays": -6, "daySign": "ix", "daySignName": "Ix", "daySignKiche": "IʼX", "number": 11, "reading": "The right arm, six days before the birth day, is 11 Ix. It is read as the other of the two sides." } ], "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" } } ``` ## SDK Quick Start ```typescript // npm install @roxyapi/sdk import { createRoxy } from '@roxyapi/sdk'; const roxy = createRoxy(process.env.ROXY_API_KEY!); const { data, error } = await roxy.mesoamericanAstrology.calculateTzolkin({ body: { date: '1990-06-15' } }); ``` ```python # pip install roxy-sdk import os from roxy_sdk import create_roxy roxy = create_roxy(api_key=os.environ["ROXY_API_KEY"]) result = roxy.mesoamerican_astrology.calculate_tzolkin(date="1990-06-15") ``` ```php // composer require roxyapi/sdk (PHP 8.2+, built on Saloon) use function RoxyAPI\Sdk\createRoxy; $roxy = createRoxy(getenv('ROXY_API_KEY')); $result = $roxy->mesoamericanAstrology->calculateTzolkin(date: '1990-06-15'); ``` ```csharp // dotnet add package RoxyApi.Sdk (.NET 8 and netstandard2.0) using RoxyApi; using Microsoft.Kiota.Abstractions; var roxy = new RoxyClient(Environment.GetEnvironmentVariable("ROXY_API_KEY")!); var data = await roxy.MesoamericanAstrology.Mayan.Tzolkin.PostAsync(new() { Date = new Date(1990, 6, 15) }); ``` TS, Python, and PHP method names come from OpenAPI `operationId` (camelCase in TS and PHP, snake_case in Python). TS returns `{ data, error, response }` — check `error` first. Python raises `RoxyAPIError`; PHP throws `RoxyApiException` (catch and switch on `$e->errorCode`). The C# (.NET) client is path-fluent — `roxy.Domain.Resource.GetAsync()` or `.PostAsync(new() { ... })`, PascalCase mirroring the URL — and throws `RoxyError` (switch on `e.Code`). ## MCP Tool Naming Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/mesoamerican-astrology`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`: ``` POST /mesoamerican-astrology/mayan/tzolkin -> post_mesoamerican_astrology_mayan_tzolkin POST /mesoamerican-astrology/mayan/chart -> post_mesoamerican_astrology_mayan_chart POST /mesoamerican-astrology/mayan/long-count/convert -> post_mesoamerican_astrology_mayan_long_count_convert ``` `tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call). ## Multi-language Support Append `?lang=` to translated endpoints. Supported on this domain: `en, de, es, fr, hi, pt, ru, tr`. English is the default. The `lang` param is ignored on endpoints that have no translatable text. ## Error Contract Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable): - `validation_error` (400, returns `issues[]` with all field errors at once) - `api_key_required` (401), `invalid_api_key` (401) - `subscription_inactive` (403), `subscription_not_found` (404) - `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field) - `rate_limit_exceeded` (429) - `internal_error` (500) Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff. ## Related Surfaces - **Guide:** [Mesoamerican integration guide](https://roxyapi.com/docs/guides/mesoamerican-astrology.md) - [Mayan Astrology API: Tzolkin Day Signs and Long Count](https://roxyapi.com/blogs/mayan-astrology-api-tzolkin-day-sign-long-count.md) - [Render Astrology Charts From LLM Tool Calls](https://roxyapi.com/blogs/render-astrology-charts-from-llm-tool-calls.md) - [AI Astrology Chat Endpoint: Why We Do Not Ship One](https://roxyapi.com/blogs/ai-astrology-chat-endpoint-bring-your-own-llm.md) - [Multilingual Astrology API: How to Verify Language Support](https://roxyapi.com/blogs/multilingual-astrology-api-verify-language-support.md) ## Full Reference For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/mesoamerican-astrology/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.