MineAPI — Developer Docs

Overview

All endpoints are HTTP GET; parameters are passed as a query string. Every response is JSON (UTF-8) wrapped in a standard envelope.

Base URL

https://minecodecraft.com/mineapi/api/

Protocol

HTTPS GET — query string parameters

Format

JSON (UTF-8), { ok, data } envelope

Caching

Deterministic results; X-Cache: HIT/MISS header

Authentication

Every request requires an API key. Send it as an Authorization: Bearer header or an X-API-Key header. Create a free account in the customer portal to get a key instantly; quotas and per-minute rate limits depend on your plan.

Response Format

Success returns ok:true with a data field. Errors return ok:false with an error object.

{ "ok": true, "data": { ... } }

{ "ok": false, "error": { "code": "bad_request", "message": "..." } }

Field Naming

Convention	Meaning
`camelCase`	All field names are camelCase, English.
`...Ms`	Unix epoch milliseconds (e.g. startMs, peakMs).
`...Iso`	ISO-8601 string (e.g. startIso, peakIso).
`...Deg / ...Arcmin`	Degrees / arc-minutes.
`signCode`	Full lowercase sign name: aries taurus gemini cancer leo virgo libra scorpio sagittarius capricorn aquarius pisces.
`...Dms`	Human-readable degree-minute string (e.g. positionDms).

Error Codes

HTTP	code	Meaning
400	`bad_request`	Invalid parameter (e.g. non-numeric lat).
404	—	Unknown endpoint.
500	`internal` / `compute_failed`	Calculation or server error.

Spec & Tools

OpenAPI 3.0.3

/mineapi/api/openapi.json

Health

/mineapi/api/health

/moon/now

Instant Moon state: phase, illumination, distance, angular diameter, sign and rise/set times.

GET/mineapi/api/moon/now

Parameters

Parameter	Type	Required	Description
date	string	Optional	epoch-ms or yyyy-MM-dd (default: now)
lat	number	Required	Latitude, degrees (+North)
lng	number	Required	Longitude, degrees (+East)

Example Request

GET /mineapi/api/moon/now?date=2026-06-21&lat=41.0082&lng=28.9784

Example Response

{
  "ok": true,
  "data": {
    "phaseCode": "first_quarter",
    "illuminationFraction": 0.4584,
    "moonAgeDays": 6.98,
    "distanceKm": 386102,
    "angularDiameterDeg": 0.5159,
    "moonSignCode": "virgo",
    "moonDay": 7,
    "moonriseMs": 1782034730931,
    "sunriseMs": 1782009125879
  }
}

/moon/cycle

The 8 phases of the current lunar cycle with super/micro/blue/black/blood and eclipse flags.

GET/mineapi/api/moon/cycle

Parameters

Parameter	Type	Required	Description
date	string	Optional	epoch-ms or yyyy-MM-dd (default: now)
lat	number	Optional	Latitude, degrees (+North) — optional (phase instants are geocentric)
lng	number	Optional	Longitude, degrees (+East) — optional (phase instants are geocentric)

Example Request

GET /mineapi/api/moon/cycle?date=2026-06-21

Example Response

{
  "ok": true,
  "data": [
    {
      "phaseIndex": 0,
      "startMs": 1781347233204,
      "peakMs": 1781492038849,
      "endMs": 1781638756525,
      "supermoon": true,
      "eclipseCategory": "",
      "moonSignCode": "gemini",
      "sunSignCode": "gemini"
    }
  ]
}

/moon/phases

All new & full moons of a year, with special-moon and eclipse flags.

GET/mineapi/api/moon/phases

Parameters

Parameter	Type	Required	Description
year	integer	Optional	Year (default: from date)
lat	number	Optional	Latitude, degrees (+North)
lng	number	Optional	Longitude, degrees (+East)
tz	string	Optional	IANA timezone (default UTC)

Example Request

GET /mineapi/api/moon/phases?year=2026&lat=41.0082&lng=28.9784&tz=Europe/Istanbul

Example Response

{
  "ok": true,
  "data": [
    {
      "phaseIndex": 4,
      "peakMs": 1767434562512,
      "supermoon": false,
      "eclipseCategory": "",
      "moonSignCode": "cancer",
      "sunSignCode": "capricorn"
    }
  ]
}

/sun/riseset

Sunrise/sunset plus civil, nautical and astronomical twilight; current Sun altitude.

GET/mineapi/api/sun/riseset

Parameters

Parameter	Type	Required	Description
date	string	Optional	epoch-ms or yyyy-MM-dd (default: now)
lat	number	Required	Latitude, degrees (+North)
lng	number	Required	Longitude, degrees (+East)
tz	string	Optional	IANA timezone (default UTC)

Example Request

GET /mineapi/api/sun/riseset?date=2026-06-21&lat=41.0082&lng=28.9784&tz=Europe/Istanbul

Example Response

{
  "ok": true,
  "data": {
    "sunriseMs": 1782009125881,
    "sunsetMs": 1782063580455,
    "civilTwilightStartMs": 1782007100830,
    "nauticalTwilightStartMs": 1782004515686,
    "astronomicalTwilightStartMs": 1782001445435,
    "altitudeDeg": 60.386
  }
}

/eclipses

Upcoming solar & lunar eclipses: type, times, lunar mansion, saros fields.

GET/mineapi/api/eclipses

Parameters

Parameter	Type	Required	Description
date	string	Optional	Look-ahead start (default: now)
sidereal	boolean	Optional	true=sidereal (Lahiri), false=tropical (default false)

Example Request

GET /mineapi/api/eclipses?date=2026-06-21&sidereal=false

Example Response

{
  "ok": true,
  "data": [
    {
      "eclipseCategory": "solecl",
      "eclipseType": "total",
      "sunSignCode": "leo",
      "startMs": 1786548857558,
      "peakMs": 1786556744204,
      "endMs": 1786564663976,
      "maxEclipseDurationSec": 5754,
      "lunarMansionPicatrixCode": "azobra"
    }
  ]
}

/eclipses/local

Local circumstances of the next eclipse for a location: visibility, contact times (c1–c4 / p1–u4), magnitude.

GET/mineapi/api/eclipses/local

Parameters

Parameter	Type	Required	Description
date	string	Optional	Look-ahead start (default: now)
lat	number	Required	Observer latitude (+North)
lng	number	Required	Observer longitude (+East)
sidereal	boolean	Optional	true=sidereal, false=tropical (default false)

Example Request

GET /mineapi/api/eclipses/local?date=2026-06-21&lat=41.0082&lng=28.9784

Example Response

{
  "ok": true,
  "data": {
    "valid": true,
    "isLunar": false,
    "type": "total",
    "visibleHere": false,
    "magnitudeAtMax": 1.0191,
    "obscurationAtMax": 1.0,
    "c1Ms": 1786553026297,
    "maxMs": 1786556750744,
    "c4Ms": 1786560318339
  }
}

/sky-events

Sky events in a rolling ~12-month window from today: equinox/solstice, meteor showers, special moon phases, astrological new year. Times are ISO-8601 (…Iso). The window is anchored to the current date; year only sets the seasonal calc context and does not move the window.

GET/mineapi/api/sky-events

Parameters

Parameter	Type	Required	Description
year	integer	Optional	Year (default: from date)
date	string	Optional	Used to derive year if year omitted

Example Request

GET /mineapi/api/sky-events?year=2026

Example Response

{
  "ok": true,
  "data": [
    { "eventCode": "moonphase_micromoon", "orderMs": 1782777389926,
      "peakIso": "2026-06-29T23:56:29", "phaseIndex": 4, "micromoon": true },
    { "eventCode": "meteor_shower", "showerKey": "perseid",
      "peakStartIso": "2026-08-12T22:00:00", "zhrMeteorsPerHour": 100,
      "parentBody": "109P/Swift-Tuttle", "hemisphereVisibility": "N" }
  ]
}

/astro/planets

Planet positions (sign, house, retrograde via speed) and house cusps.

GET/mineapi/api/astro/planets

Parameters

Parameter	Type	Required	Description
date	string	Optional	epoch-ms or yyyy-MM-dd (default: now)
lat	number	Required	Latitude (+North)
lng	number	Required	Longitude (+East)
houseSystem	string	Optional	0=Placidus, 7=Whole Sign… (default 0)

Example Request

GET /mineapi/api/astro/planets?date=2026-06-21&lat=41.0082&lng=28.9784&houseSystem=0

Example Response

{
  "ok": true,
  "data": {
    "planets": [
      { "body": "sun", "signCode": "cancer", "longitudeDeg": 90,
        "speedDegPerDay": 0.9544, "ruler": "moon", "houseNumber": 9 }
    ],
    "houses": [ { "houseNumber": 1, "signCode": "...", "cuspAngleDeg": 0 } ]
  }
}

/astro/natal-chart

Birth chart: planets + houses + aspects + lunar mansion in one call.

GET/mineapi/api/astro/natal-chart

Parameters

Parameter	Type	Required	Description
date	string	Required	Birth date-time, epoch-ms or yyyy-MM-dd
lat	number	Required	Birth latitude (+North)
lng	number	Required	Birth longitude (+East)
houseSystem	string	Optional	0=Placidus, 7=Whole Sign… (default 0)
sidereal	boolean	Optional	Lunar mansion sidereal? (default false)
lang	string	Optional	Locale for lunar-mansion texts (default en)

Example Request

GET /mineapi/api/astro/natal-chart?date=1990-05-15&lat=41.0082&lng=28.9784&lang=en

Example Response

{
  "ok": true,
  "data": {
    "planets": [ { "body": "sun", "signCode": "taurus", "houseNumber": 9 } ],
    "houses":  [ ... ],
    "aspects": [ { "firstBody": "sun", "secondBody": "moon",
                   "aspectAngleDeg": 120, "orbDeg": 3 } ],
    "lunarMansion": { "mansionNumber": 13, "picatrixCode": "azimech" }
  }
}

/astro/aspects

Upcoming Moon–planet major aspects within a day window.

GET/mineapi/api/astro/aspects

Parameters

Parameter	Type	Required	Description
date	string	Optional	Window start (default: now)
days	integer	Optional	Window length in days, 1–60 (default 7)

Example Request

GET /mineapi/api/astro/aspects?date=2026-06-21&days=7

Example Response

{
  "ok": true,
  "data": [
    { "body": "jupiter", "aspectAngleDeg": 60, "retrograde": false, "startMs": 1782063172265 },
    { "body": "sun", "aspectAngleDeg": 90, "retrograde": false, "startMs": 1782078908202 }
  ]
}

/astro/planetary-hours

Classical (Chaldean) planetary hours — 24 hours from sunrise.

GET/mineapi/api/astro/planetary-hours

Parameters

Parameter	Type	Required	Description
date	string	Optional	epoch-ms or yyyy-MM-dd (default: now)
lat	number	Required	Latitude (+North)
lng	number	Required	Longitude (+East)
tz	string	Required	IANA timezone (required — ruling planet depends on local weekday)

Example Request

GET /mineapi/api/astro/planetary-hours?date=2026-06-21&lat=41.0082&lng=28.9784&tz=Europe/Istanbul

Example Response

{
  "ok": true,
  "data": {
    "hours": [
      { "hourIndex": 1, "dayOrNight": "day", "rulingPlanet": "sun",
        "startMs": 1782009125879, "endMs": 1782013663760 }
    ]
  }
}

/astro/lunar-mansion

Lunar mansion (1–28; Picatrix / Ibn Arabi names; tropical or sidereal).

GET/mineapi/api/astro/lunar-mansion

Parameters

Parameter	Type	Required	Description
date	string	Optional	epoch-ms or yyyy-MM-dd (default: now)
sidereal	boolean	Optional	true=sidereal (Lahiri), false=tropical (default false)
lang	string	Optional	Locale for names/texts (default en)

Example Request

GET /mineapi/api/astro/lunar-mansion?date=2026-06-21&lang=en

Example Response

{
  "ok": true,
  "data": {
    "mansionNumber": 13,
    "startMs": 1781989859999,
    "endMs": 1782075300000,
    "startSignCode": "virgo",
    "picatrixCode": "azimech",
    "ibnArabiCode": "nur",
    "element": "earth",
    "polarity": "mix",
    "esmaName": "Musavvir"
  }
}

/astro/sabian

Sabian symbol for an ecliptic degree (standard reference set).

GET/mineapi/api/astro/sabian

Parameters

Parameter	Type	Required	Description
lon	number	Optional	Ecliptic longitude 0–360. If omitted, uses the Moon's longitude at date.
date	string	Optional	Used when lon is omitted (default: now)
lang	string	Optional	Locale for symbol text (default en)

Example Request

GET /mineapi/api/astro/sabian?lon=120.5&lang=en

Example Response

{
  "ok": true,
  "data": {
    "signCode": "leo",
    "signDegree": 0,
    "arcmin": 30,
    "sabianShort": "A man suffers a stroke while spending his life energy on his ambitions.",
    "sabianLong": "..."
  }
}

/astro/voc

Void-of-course Moon periods for the current month. lastAspectBodyId is a Swiss Ephemeris body id (integer).

GET/mineapi/api/astro/voc

Parameters

Parameter	Type	Required	Description
date	string	Optional	A date within the target month (default: now)
tz	string	Optional	IANA timezone (default UTC)

Example Request

GET /mineapi/api/astro/voc?date=2026-06-21&tz=Europe/Istanbul

Example Response

{
  "ok": true,
  "data": [
    {
      "startMs": 1780233660000,
      "endMs": 1780363200000,
      "lastAspectBodyId": 6,
      "lastAspectAngleDeg": 120,
      "moonSignCode": "sagittarius",
      "bodySignCode": "aries"
    }
  ]
}

/astro/uranian-planets

Hamburg / Uranian planets (Cupido…Poseidon) ecliptic longitudes in degrees.

GET/mineapi/api/astro/uranian-planets

Parameters

Parameter	Type	Required	Description
date	string	Optional	epoch-ms or yyyy-MM-dd (default: now)

Example Request

GET /mineapi/api/astro/uranian-planets?date=2026-06-21

Example Response

{
  "ok": true,
  "data": {
    "cupido": 280.2616, "hades": 104.996, "zeus": 204.824,
    "kronos": 106.3137, "apollon": 216.3982, "admetos": 65.4917,
    "vulkanus": 124.2864, "poseidon": 226.2946
  }
}

/astro/season

Hemisphere + season flags derived from the Sun's ecliptic longitude.

GET/mineapi/api/astro/season

Parameters

Parameter	Type	Required	Description
date	string	Optional	epoch-ms or yyyy-MM-dd (default: now)
lat	number	Required	Latitude (+North / -South)

Example Request

GET /mineapi/api/astro/season?date=2026-06-21&lat=41.0082

Example Response

{
  "ok": true,
  "data": {
    "isNorthern": true, "isSouthern": false,
    "isSpring": false, "isSummer": true, "isAutumn": false, "isWinter": false
  }
}

/astro/fixed-star-syrma

Conjunction window of Moon/Sun/Mars with the fixed star Syrma (ι Vir). Returns active=false when none; otherwise active, body and enterMs/exitMs.

GET/mineapi/api/astro/fixed-star-syrma

Parameters

Parameter	Type	Required	Description
date	string	Optional	epoch-ms or yyyy-MM-dd (default: now)

Example Request

GET /mineapi/api/astro/fixed-star-syrma?date=2026-03-02

Example Response

{ "ok": true, "data": { "active": false } }

{ "ok": true, "data": { "active": true, "body": "moon",
                        "enterMs": 1772668800000, "exitMs": 1772690400000 } }

/calendar/monthly

Monthly sky calendar: for each day the Moon's sign, the sign-change time (0 if none) and the main phase.

GET/mineapi/api/calendar/monthly

Parameters

Parameter	Type	Required	Description
year	integer	Optional	Year (default: from date)
month	integer	Optional	Month 1–12 (default: from date)
lat	number	Required	Latitude (+North)
lng	number	Required	Longitude (+East)
tz	string	Optional	IANA timezone (day boundaries; default UTC)
lang	string	Optional	Locale for week start (default en)

Example Request

GET /mineapi/api/calendar/monthly?year=2026&month=6&lat=41.0082&lng=28.9784&tz=Europe/Istanbul

Example Response

{
  "ok": true,
  "data": [
    {
      "noonMs": 1780304400000,
      "zodiacChangeMs": 0,
      "moonSignCode": "sagittarius",
      "moonPhase": "",
      "dayOfWeek": 2
    }
  ]
}

MineAPI Developer Docs

Overview

Authentication

Response Format

Field Naming

Error Codes

Spec & Tools

/moon/now

Parameters

Example Request

Example Response

/moon/cycle

Parameters

Example Request

Example Response

/moon/phases

Parameters

Example Request

Example Response

/sun/riseset

Parameters

Example Request

Example Response

/eclipses

Parameters

Example Request

Example Response

/eclipses/local

Parameters

Example Request

Example Response

/sky-events

Parameters

Example Request

Example Response

/astro/planets

Parameters

Example Request

Example Response

/astro/natal-chart

Parameters

Example Request

Example Response

/astro/aspects

Parameters

Example Request

Example Response

/astro/planetary-hours

Parameters

Example Request

Example Response

/astro/lunar-mansion

Parameters

Example Request

Example Response

/astro/sabian

Parameters

Example Request

Example Response

/astro/voc

Parameters

Example Request

Example Response

/astro/uranian-planets

Parameters

Example Request

Example Response

/astro/season

Parameters

Example Request

Example Response

/astro/fixed-star-syrma

Parameters

Example Request

Example Response

/calendar/monthly

Parameters

Example Request

Example Response