Mayan Calendar API

About the Mayan Calendar API

A Mayan calendar API that converts any Gregorian date into the Long Count, the 260-day Tzolkin and the 365-day Haab. Send a date such as 2024-12-21 and get back 13.0.12.3.3, 6 Akbal and 6 Kankin, each as a ready-to-display string. The conversion uses the GMT (Goodman-Martinez-Thompson) correlation constant, the standard alignment between the two calendars.

It suits educational content, historical research, and cultural applications: museum and classroom tools, a "your Mayan birthday" feature, date widgets for heritage sites, or puzzle and game content built around the baktun cycles.

The Free plan returns the Gregorian date and the formatted Long Count, Tzolkin and Haab strings. Paid plans break each of those into its numeric parts (baktun, katun, tun, winal and kin; the Tzolkin number and day name; the Haab day and month name) and add the combined Calendar Round and the day count since the Mayan creation date, which you need to do arithmetic on the dates yourself.

How it works

The date parameter is a Gregorian date in YYYY-MM-DD form. It is converted to a Julian Day Number using the proleptic Gregorian calendar, and the GMT correlation constant 584283 is subtracted to give daysSinceEpoch, the number of days since the Long Count date 0.0.0.0.0. Every other field is derived from that one integer.

longCount divides the day count by 144,000 for baktun, then 7,200 for katun, 360 for tun and 20 for winal, with the remainder as kin. formatted joins them with dots.

tzolkin counts forward from the epoch day 4 Ahau. number cycles 1 to 13 and dayName cycles through the 20 day names from Imix to Ahau, so the pair repeats every 260 days. haab counts forward from 8 Kumku: the year is 18 months of 20 days plus the 5-day Wayeb, so day runs 0 to 19 (0 to 4 in Wayeb) and monthName is one of the 19 month names. Names use the spellings shown in the response, such as Akbal and Kankin, not alternate orthographies.

calendarRound is the Tzolkin and Haab strings joined with a space; the same combination recurs every 52 Haab years. gregorian echoes the input, zero-padded.

On the Free plan the formatted strings and gregorian are returned, and the individual numeric and name fields, calendarRound and daysSinceEpoch are removed.

What people use it for

Educational Tools

Teach about ancient Mesoamerican calendar systems

Cultural Applications

Display Mayan dates for heritage and cultural apps

Historical Research

Convert dates for archaeological and historical study

Novelty Apps

Generate personalized Mayan birth dates

Ways to call it

One endpoint, many ways in — REST with JSON, XML, YAML and CSV, plus GraphQL and an MCP interface for AI agents.

JSON

Default REST response

XML

Markup format

YAML

Human-readable

CSV

Tabular export

Beta

GraphQL

Query language

New

MCP

For AI agents

Request parameters — GET /v1/mayancalendar

Sent in the query string. Premium parameters are accepted on every plan but only take effect on plans that include them. Anything not listed here is dropped rather than passed through.

Required

1
2

curl "https://api.apiverve.com/v1/mayancalendar?date=2024-12-21" \
  -H "x-api-key: YOUR_API_KEY"

Authentication

Send your key in the x-api-key header. That is the only auth step — no token exchange, and no per-endpoint scope to configure.

Response — GET /v1/mayancalendar

Every APIVerve endpoint returns the same three top-level keys, so one response handler covers your whole integration: status, error and data. Only data changes shape.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "status": "ok",
  "error": null,
  "data": {
    "gregorian": "2024-12-21",
    "longCount": {
      "formatted": "13.0.12.3.3",
      "baktun": 13,
      "katun": 0,
      "tun": 12,
      "winal": 3,
      "kin": 3
    },
    "tzolkin": {
      "number": 6,
      "dayName": "Akbal",
      "formatted": "6 Akbal"
    },
    "haab": {
      "day": 6,
      "monthName": "Kankin",
      "formatted": "6 Kankin"
    },
    "calendarRound": "6 Akbal 6 Kankin",
    "daysSinceEpoch": 1876383
  }
}

Response fields

Paths are relative to data. Premium fields are absent rather than zeroed on plans that do not include them, so check for presence instead of comparing to 0.

Response headers

Every response carries your balance, so your own code always knows where it stands without polling anything. All four are exposed to browsers through CORS.

Errors

Read the HTTP status first, then error for the specific reason. The body names the parameter that has to change.

What a call costs — 1 credits per call

Credits are shared across every APIVerve API — one balance, one key, one bill. Failed requests never count against it, so a rejected input costs nothing.

Calls are what the credits buy at this API's rate — spend them here, on any of the other APIs, or across both. Nothing is reserved per endpoint.

Zero-code embed — one snippet, no backend

Drop an interactive Mayan Calendar form onto any page. The widget calls the API for you, so no key ever appears in your markup and there is nothing to deploy.

Changelog — Mayan Calendar API

Every change to this endpoint, newest first. Breaking changes ship as a new version and the previous one keeps serving — response fields are added, never removed or retyped in place, so an integration written against v1 keeps working.

Currently v1