MineAPI — Geliştirici Dokümanı

Genel Bakış

Tüm uçlar HTTP GET'tir; parametreler query string ile gönderilir. Her yanıt standart bir zarf içinde JSON (UTF-8) döner.

Base URL

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

Protokol

HTTPS GET — query string parametreleri

Biçim

JSON (UTF-8), { ok, data } zarfı

Önbellek

Sonuçlar deterministik; X-Cache: HIT/MISS başlığı

Kimlik Doğrulama

Her istek bir API anahtarı gerektirir. Anahtarı Authorization: Bearer başlığıyla ya da X-API-Key başlığıyla gönderin. Müşteri panelinden ücretsiz hesap açıp anahtarınızı anında alın; kotalar ve dakika limitleri planınıza bağlıdır.

Yanıt Biçimi

Başarı ok:true ve data alanı döner. Hatalar ok:false ve bir error nesnesi döner.

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

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

Alan Adlandırma

Kural	Anlam
`camelCase`	Tüm alan adları camelCase, İngilizce.
`...Ms`	Unix epoch milisaniye (ör. startMs, peakMs).
`...Iso`	ISO-8601 string (ör. startIso, peakIso).
`...Deg / ...Arcmin`	Derece / yay-dakikası.
`signCode`	Tam küçük-harf burç adı: aries taurus gemini cancer leo virgo libra scorpio sagittarius capricorn aquarius pisces.
`...Dms`	İnsan-okur derece-dakika metni (ör. positionDms).

Hata Kodları

HTTP	code	Anlam
400	`bad_request`	Geçersiz parametre (ör. sayısal olmayan lat).
404	—	Bilinmeyen uç.
500	`internal` / `compute_failed`	Hesaplama veya sunucu hatası.

Şema & Araçlar

OpenAPI 3.0.3

/mineapi/api/openapi.json

Health

/mineapi/api/health

/moon/now

Anlık Ay durumu: faz, aydınlanma, mesafe, açısal çap, burç ve doğuş/batış zamanları.

GET/mineapi/api/moon/now

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	epoch-ms veya yyyy-MM-dd (vars. şimdi)
lat	number	Zorunlu	Enlem, derece (+Kuzey)
lng	number	Zorunlu	Boylam, derece (+Doğu)

Örnek İstek

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

Örnek Yanıt

{
  "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

İçinde bulunulan ay döngüsünün 8 fazı; super/micro/blue/black/blood ve tutulma bayraklarıyla.

GET/mineapi/api/moon/cycle

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	epoch-ms veya yyyy-MM-dd (vars. şimdi)
lat	number	Opsiyonel	Enlem, derece (+Kuzey) — opsiyonel (faz anları geocentric)
lng	number	Opsiyonel	Boylam, derece (+Doğu) — opsiyonel (faz anları geocentric)

Örnek İstek

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

Örnek Yanıt

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

/moon/phases

Bir yılın tüm yeni ay/dolunayları; özel-ay ve tutulma bayraklarıyla.

GET/mineapi/api/moon/phases

Parametreler

Parametre	Tip	Zorunlu	Açıklama
year	integer	Opsiyonel	Yıl (vars. date'ten)
lat	number	Opsiyonel	Enlem, derece (+Kuzey)
lng	number	Opsiyonel	Boylam, derece (+Doğu)
tz	string	Opsiyonel	IANA saat dilimi (vars. UTC)

Örnek İstek

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

Örnek Yanıt

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

/sun/riseset

Güneş doğuş/batış artı sivil, denizci ve astronomik alacakaranlık; anlık Güneş yüksekliği.

GET/mineapi/api/sun/riseset

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	epoch-ms veya yyyy-MM-dd (vars. şimdi)
lat	number	Zorunlu	Enlem, derece (+Kuzey)
lng	number	Zorunlu	Boylam, derece (+Doğu)
tz	string	Opsiyonel	IANA saat dilimi (vars. UTC)

Örnek İstek

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

Örnek Yanıt

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

/eclipses

İleriye dönük güneş ve ay tutulmaları: tip, zaman, ay konağı, saros alanları.

GET/mineapi/api/eclipses

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	İleri-bakış başlangıcı (vars. şimdi)
sidereal	boolean	Opsiyonel	true=sidereal (Lahiri), false=tropikal (vars. false)

Örnek İstek

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

Örnek Yanıt

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

/eclipses/local

Bir konum için sonraki tutulmanın yerel koşulları: görünürlük, temas zamanları (c1–c4 / p1–u4), büyüklük.

GET/mineapi/api/eclipses/local

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	İleri-bakış başlangıcı (vars. şimdi)
lat	number	Zorunlu	Gözlemci enlemi (+Kuzey)
lng	number	Zorunlu	Gözlemci boylamı (+Doğu)
sidereal	boolean	Opsiyonel	true=sidereal, false=tropikal (vars. false)

Örnek İstek

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

Örnek Yanıt

{
  "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

Bugünden itibaren ~12 aylık kayan penceredeki gök olayları: ekinoks/gündönümü, meteor yağmurları, özel ay fazları, astrolojik yeni yıl. Zamanlar ISO-8601 (…Iso). Pencere güncel tarihe sabitlidir; year yalnızca mevsim hesabı bağlamını verir, pencereyi taşımaz.

GET/mineapi/api/sky-events

Parametreler

Parametre	Tip	Zorunlu	Açıklama
year	integer	Opsiyonel	Yıl (vars. date'ten)
date	string	Opsiyonel	year verilmezse yıl bundan türetilir

Örnek İstek

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

Örnek Yanıt

{
  "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

Gezegen konumları (burç, ev, hız ile retrograd) ve ev cuspları.

GET/mineapi/api/astro/planets

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	epoch-ms veya yyyy-MM-dd (vars. şimdi)
lat	number	Zorunlu	Enlem (+Kuzey)
lng	number	Zorunlu	Boylam (+Doğu)
houseSystem	string	Opsiyonel	0=Placidus, 7=Whole Sign… (vars. 0)

Örnek İstek

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

Örnek Yanıt

{
  "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

Doğum haritası: tek çağrıda gezegenler + evler + aspektler + ay konağı.

GET/mineapi/api/astro/natal-chart

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Zorunlu	Doğum tarih-saati, epoch-ms veya yyyy-MM-dd
lat	number	Zorunlu	Doğum enlemi (+Kuzey)
lng	number	Zorunlu	Doğum boylamı (+Doğu)
houseSystem	string	Opsiyonel	0=Placidus, 7=Whole Sign… (vars. 0)
sidereal	boolean	Opsiyonel	Ay konağı sidereal mi? (vars. false)
lang	string	Opsiyonel	Ay konağı metinleri için dil (vars. en)

Örnek İstek

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

Örnek Yanıt

{
  "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

Belirli bir gün penceresinde Ay–gezegen majör açıları.

GET/mineapi/api/astro/aspects

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	Pencere başlangıcı (vars. şimdi)
days	integer	Opsiyonel	Pencere uzunluğu gün, 1–60 (vars. 7)

Örnek İstek

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

Örnek Yanıt

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

/astro/planetary-hours

Klasik (Kaldean) gezegen saatleri — gün doğumundan 24 saat.

GET/mineapi/api/astro/planetary-hours

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	epoch-ms veya yyyy-MM-dd (vars. şimdi)
lat	number	Zorunlu	Enlem (+Kuzey)
lng	number	Zorunlu	Boylam (+Doğu)
tz	string	Zorunlu	IANA saat dilimi (zorunlu — yönetici gezegen yerel hafta gününe bağlı)

Örnek İstek

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

Örnek Yanıt

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

/astro/lunar-mansion

Ay konağı (1–28; Picatrix / İbn Arabi adları; tropikal veya sidereal).

GET/mineapi/api/astro/lunar-mansion

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	epoch-ms veya yyyy-MM-dd (vars. şimdi)
sidereal	boolean	Opsiyonel	true=sidereal (Lahiri), false=tropikal (vars. false)
lang	string	Opsiyonel	Ad/metin dili (vars. en)

Örnek İstek

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

Örnek Yanıt

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

/astro/sabian

Bir ekliptik dereceye karşılık Sabian sembolü (standart referans külliyatı).

GET/mineapi/api/astro/sabian

Parametreler

Parametre	Tip	Zorunlu	Açıklama
lon	number	Opsiyonel	Ekliptik boylam 0–360. Verilmezse date'teki Ay boylamı kullanılır.
date	string	Opsiyonel	lon verilmezse kullanılır (vars. şimdi)
lang	string	Opsiyonel	Sembol metni dili (vars. en)

Örnek İstek

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

Örnek Yanıt

{
  "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

İçinde bulunulan ay için boşlukta-seyir (VOC) dönemleri. lastAspectBodyId bir Swiss Ephemeris cisim id'sidir (tamsayı).

GET/mineapi/api/astro/voc

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	Hedef ay içindeki bir tarih (vars. şimdi)
tz	string	Opsiyonel	IANA saat dilimi (vars. UTC)

Örnek İstek

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

Örnek Yanıt

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

/astro/uranian-planets

Hamburg / Uranian gezegenleri (Cupido…Poseidon) ekliptik boylamları, derece.

GET/mineapi/api/astro/uranian-planets

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	epoch-ms veya yyyy-MM-dd (vars. şimdi)

Örnek İstek

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

Örnek Yanıt

{
  "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

Güneşin ekliptik boylamından türetilen yarımküre + mevsim bayrakları.

GET/mineapi/api/astro/season

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	epoch-ms veya yyyy-MM-dd (vars. şimdi)
lat	number	Zorunlu	Enlem (+Kuzey / -Güney)

Örnek İstek

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

Örnek Yanıt

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

/astro/fixed-star-syrma

Ay/Güneş/Mars'ın Syrma (ι Vir) sabit yıldızıyla kavuşum penceresi. Yoksa active=false; varsa active, body ve enterMs/exitMs.

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

Parametreler

Parametre	Tip	Zorunlu	Açıklama
date	string	Opsiyonel	epoch-ms veya yyyy-MM-dd (vars. şimdi)

Örnek İstek

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

Örnek Yanıt

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

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

/calendar/monthly

Aylık gök takvimi: her gün için Ay'ın burcu, burç değişim anı (yoksa 0) ve ana faz.

GET/mineapi/api/calendar/monthly

Parametreler

Parametre	Tip	Zorunlu	Açıklama
year	integer	Opsiyonel	Yıl (vars. date'ten)
month	integer	Opsiyonel	Ay 1–12 (vars. date'ten)
lat	number	Zorunlu	Enlem (+Kuzey)
lng	number	Zorunlu	Boylam (+Doğu)
tz	string	Opsiyonel	IANA saat dilimi (gün sınırları; vars. UTC)
lang	string	Opsiyonel	Hafta başı için dil (vars. en)

Örnek İstek

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

Örnek Yanıt

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

MineAPI Geliştirici Dokümanı

Genel Bakış

Kimlik Doğrulama

Yanıt Biçimi

Alan Adlandırma

Hata Kodları

Şema & Araçlar

/moon/now

Parametreler

Örnek İstek

Örnek Yanıt

/moon/cycle

Parametreler

Örnek İstek

Örnek Yanıt

/moon/phases

Parametreler

Örnek İstek

Örnek Yanıt

/sun/riseset

Parametreler

Örnek İstek

Örnek Yanıt

/eclipses

Parametreler

Örnek İstek

Örnek Yanıt

/eclipses/local

Parametreler

Örnek İstek

Örnek Yanıt

/sky-events

Parametreler

Örnek İstek

Örnek Yanıt

/astro/planets

Parametreler

Örnek İstek

Örnek Yanıt

/astro/natal-chart

Parametreler

Örnek İstek

Örnek Yanıt

/astro/aspects

Parametreler

Örnek İstek

Örnek Yanıt

/astro/planetary-hours

Parametreler

Örnek İstek

Örnek Yanıt

/astro/lunar-mansion

Parametreler

Örnek İstek

Örnek Yanıt

/astro/sabian

Parametreler

Örnek İstek

Örnek Yanıt

/astro/voc

Parametreler

Örnek İstek

Örnek Yanıt

/astro/uranian-planets

Parametreler

Örnek İstek

Örnek Yanıt

/astro/season

Parametreler

Örnek İstek

Örnek Yanıt

/astro/fixed-star-syrma

Parametreler

Örnek İstek

Örnek Yanıt

/calendar/monthly

Parametreler

Örnek İstek

Örnek Yanıt