POST/api/astro/eclipse/visibility-path/1 kredi

Tutulma görünürlük yolu

Bir güneş tutulmasının tam olarak görüldüğü bölge, haritaya çizilebilecek bir koordinat çizgisi olarak. Verdiğiniz andan sonraki ilk güneş tutulmasını bulur, ardından Ay'ın gölge ekseninin Dünya'ya değdiği noktayı örnekleyerek sıralı enlem/boylam çiftleri döndürür. 2026-08-12 tarihindeki tam tutulmada bu iz Sibirya'nın kutup bölgesinden başlar, kutbun üzerinden geçer, İzlanda'nın üzerinden güneye iner ve İber Yarımadası açıklarında Atlas Okyanusu'na çıkar — bir yerin tam mı yoksa parçalı mı tutulma göreceğini belirleyen yol budur. Örneklenen aralık tutulmanın tamamı değil, tam evredir (ya da halkalı evre). Bunun dışında gölge ekseni Dünya'yı hiç kesmez ve merkez çizgisi oluşmaz; bu yüzden yalnızca parçalı olan bir tutulmada, var olmayan bir çizgi yerine path_traced_over değeri "none" olan boş bir yol döner. Eksenin Dünya'yı kesmediği noktalar atlanır; dolayısıyla sample_count istediğiniz örnek sayısından az olabilir. Ayrıca en büyük tutulma noktasını; büyüklüğü, örtülme oranı ve tutulma kataloglarının dizinlemede kullandığı tanımlayıcı olan Saros serisi ve üye numarasıyla birlikte döndürür. Yol zamanları UTC'dir ve sonlarında Z bulunur. İz dünyanın bir ucundan öbürüne uzandığı için, diğer tutulma endpoint'lerinin kullandığı saat farkı sizden dünyanın öbür yarısındaki bir nokta için yanıltıcı olurdu. Tam gölge ve yarı gölge kenar sınırları döndürülmez: bu hesaplamada yalnızca merkez çizgisi hesaplanır; boş alanları raporlamak 0N 0E noktasını bir sınır gibi yayımlamak olurdu.

https://api.occultapi.com/api/astro/eclipse/visibility-path/

İsteği deneyin

Kimlik doğrulama

Anahtarınızı X-API-Key başlığında gönderin. Anahtar, sunucu tarafında saklanması gereken bir kimlik bilgisidir; tarayıcıda çalışan JavaScript'e veya mobil uygulamaya asla koymayın.

X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/json

İstek alanları

Alan	Tür	Zorunlu	Notlar
date_time	string (date-time)	zorunlu	Hesaplamanın yapılacağı an, ISO 8601 biçiminde. Değere HER ZAMAN bir saat farkı ya da sonda Z ekleyin - saat dilimi içermeyen bir değer UTC değil, Asia/Kolkata (UTC+05:30) olarak okunur ve 200 koduyla bir önceki günün sonucunu döndürebilir. '2026-09-01T06:00:00Z' ile '2026-09-01 06:00:00' farklı anlardır ve farklı sonuç verir.
centrality	string	isteğe bağlı	Merkezi, Ay'ın gölge ekseninin Dünya'ya gerçekten değdiği anlamına gelir. Yalnızca eclipse_type 'any' değilse anlamlıdır. `anycentralnon-central`
direction	string	isteğe bağlı	date_time değerinden ileriye ya da geriye doğru arar. `afterbefore`
eclipse_type	string	isteğe bağlı	Aramayı tek bir güneş tutulması türüyle sınırlar. `anytotalannularpartialhybrid`
elevation	number (double)	isteğe bağlı
keys	array	isteğe bağlı	Döndürülecek hesaplamaların adlarını içeren liste. Bu endpoint'in anahtar tablosuna bakın; tanınmayan bir ad varsa isteğin tamamı reddedilir. Kaç anahtar isterseniz isteyin bir çağrı bir kredi tutar; bu yüzden birkaç ayrı çağrı yapmak yerine ihtiyacınız olan her şeyi tek seferde isteyin.
latitude	number (double)	isteğe bağlı	Yerin enlemi, ondalık derece cinsinden. Pozitif değer kuzeyi, negatif değer güneyi gösterir. Örnek: Jaipur için 26.9124, New York için 40.7128. Dakika ve saniye kabul edilmez - önce ondalık dereceye çevirin.
longitude	number (double)	isteğe bağlı	Yerin boylamı, ondalık derece cinsinden. Pozitif değer doğuyu, negatif değer batıyı gösterir. Örnek: Jaipur için 75.7873, New York için -74.0060. İşarete dikkat edin: eksi işaretini unutursanız New York Çin'e düşer.
samples	integer	isteğe bağlı	Yol boyunca kaç nokta hesaplanacağı. Sayı arttıkça çizgi daha düzgün olur; en fazla 120. min 2 · max 120
timezone_as_float	number (double)	isteğe bağlı	Yerin UTC farkı, saat cinsinden ondalık sayı olarak. Örnek: Hindistan için 5.5 (UTC+05:30), kışın New York için -5, Nepal için 5.75. Bu değer date_time ile karşılaştırılıp DOĞRULANMAZ - ikisi birbirini tutmazsa yanlış an için başarılı bir yanıt alırsınız; bu yüzden ikisini de aynı kaynaktan alın. Bugünkü farkı değil, o tarihte geçerli olan farkı kullanın: yaz saati uygulayan bir ülkede yaz aylarında doğan biri için yaz saati farkı gerekir. min -12 · max 14

Örnek istek

curl -X POST https://api.occultapi.com/api/astro/eclipse/visibility-path/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_time":"2026-01-01T00:00:00+00:00","timezone_as_float":0,"eclipse_type":"total","direction":"after","samples":24}'

Yanıt

{
  "data": {
    "found": true,
    "eclipse": {
      "type": "total",
      "centrality": "central",
      "maximum": "2026-08-12T17:45:57Z",
      "times": {
        "maximum": "2026-08-12T17:45:57Z",
        "local_apparent_noon": "2026-08-12T17:03:51Z",
        "begin": "2026-08-12T15:34:30Z",
        "end": "2026-08-12T19:57:57Z",
        "totality_begin": "2026-08-12T16:58:05Z",
        "totality_end": "2026-08-12T18:34:00Z",
        "centre_line_begin": "2026-08-12T17:00:06Z",
        "centre_line_end": "2026-08-12T18:32:01Z"
      }
    },
    "path_traced_over": "totality",
    "requested_samples": 24,
    "sample_count": 25,
    "path": [
      {
        "datetime_utc": "2026-08-12T16:58:05Z",
        "latitude": 74.877805,
        "longitude": 117.671955
      },
      {
        "datetime_utc": "2026-08-12T17:02:04Z",
        "latitude": 82.361743,
        "longitude": 112.418144
      },
      {
        "datetime_utc": "2026-08-12T17:06:04Z",
        "latitude": 87.329632,
        "longitude": 80.477549
      },
      {
        "datetime_utc": "2026-08-12T17:10:04Z",
        "latitude": 86.790315,
        "longitude": -2.537547
      },
      {
        "datetime_utc": "2026-08-12T17:14:04Z",
        "latitude": 83.870696,
        "longitude": -21.42455
      },
      {
        "datetime_utc": "2026-08-12T17:18:03Z",
        "latitude": 81.057681,
        "longitude": -26.067301
      },
      {
        "datetime_utc": "2026-08-12T17:22:03Z",
        "latitude": 78.429119,
        "longitude": -27.559629
      },
      {
        "datetime_utc": "2026-08-12T17:26:03Z",
        "latitude": 75.963829,
        "longitude": -27.916291
      },
      {
        "datetime_utc": "2026-08-12T17:30:03Z",
        "latitude": 73.627499,
        "longitude": -27.753208
      },
      {
        "datetime_utc": "2026-08-12T17:34:03Z",
        "latitude": 71.393131,
        "longitude": -27.30956
      },
      {
        "datetime_utc": "2026-08-12T17:38:02Z",
        "latitude": 69.248567,
        "longitude": -26.695107
      },
      {
        "datetime_utc": "2026-08-12T17:42:02Z",
        "latitude": 67.159166,
        "longitude": -25.955597
      },
      {
        "datetime_utc": "2026-08-12T17:46:02Z",
        "latitude": 65.120178,
        "longitude": -25.117197
      },
      {
        "datetime_utc": "2026-08-12T17:50:02Z",
        "latitude": 63.119601,
        "longitude": -24.188769
      },
      {
        "datetime_utc": "2026-08-12T17:54:02Z",
        "latitude": 61.146536,
        "longitude": -23.169557
      },
      {
        "datetime_utc": "2026-08-12T17:58:01Z",
        "latitude": 59.19864,
        "longitude": -22.056292
      },
      {
        "datetime_utc": "2026-08-12T18:02:01Z",
        "latitude": 57.248921,
        "longitude": -20.82451
      },
      {
        "datetime_utc": "2026-08-12T18:06:01Z",
        "latitude": 55.293732,
        "longitude": -19.455163
      },
      {
        "datetime_utc": "2026-08-12T18:10:01Z",
        "latitude": 53.318925,
        "longitude": -17.9132
      },
      {
        "datetime_utc": "2026-08-12T18:14:01Z",
        "latitude": 51.305904,
        "longitude": -16.145189
      },
      {
        "datetime_utc": "2026-08-12T18:18:00Z",
        "latitude": 49.236237,
        "longitude": -14.074018
      },
      {
        "datetime_utc": "2026-08-12T18:22:00Z",
        "latitude": 47.046663,
        "longitude": -11.526755
      },
      {
        "datetime_utc": "2026-08-12T18:26:00Z",
        "latitude": 44.648895,
        "longitude": -8.169827
      },
      {
        "datetime_utc": "2026-08-12T18:30:00Z",
        "latitude": 41.718798,
        "longitude": -2.829804
      },
      {
        "datetime_utc": "2026-08-12T18:34:00Z",
        "latitude": 37.795826,
        "longitude": 4.632462
      }
    ],
    "greatest_eclipse": {
      "datetime_utc": "2026-08-12T17:45:57Z",
      "latitude": 65.162226,
      "longitude": -25.135594,
      "attributes": {
        "solar_diameter_fraction_covered": 1.0177529811525174,
        "lunar_to_solar_diameter_ratio": 1.0395246462080372,
        "obscuration": 1.0806114900739452,
        "core_shadow_diameter_km": -132.45861086856522,
        "sun_azimuth": 68.50274145564674,
        "sun_true_altitude": 25.738278484149753,
        "sun_apparent_altitude": 25.771879784684916,
        "moon_elongation": 0.0010572200151275264,
        "magnitude_nasa": 1.0395246462080372,
        "saros_series": 126,
        "saros_member": 48
      },
      "saros": {
        "series": 126,
        "member": 48
      }
    },
    "notes": {
      "path": "Sampled evenly across totality. Times are UTC.",
      "limits": "Umbra and penumbra limits are unavailable: only the central line is computed for this calculation."
    }
  },
  "status": 200,
  "is_error": false,
  "message": "successful"
}

Yukarıdaki isteğin birebir aynısıyla yapılan gerçek bir çağrıdan alındı. Sonuçlar data altında yer alır.

Hatalar

Kredi ve kullanım hataları { "error": "…", "message": "<code>", "is_error": true } döndürür. Kullanıcıya error değerini gösterin, kodunuzda ise message değerine göre karar verin. Ayrıntılar için hata referansına bakın.