Add the Islamic Date to your app

If you’re building software that needs the Islamic date, here’s the good news: you don’t need a paid API or even a network call. The Hijri date follows from any Gregorian date through a well-known algorithm. This guide gives you the logic, working code, and the single calibration detail most implementations get wrong.

# Compute it yourself

The conversion is pure integer arithmetic: turn the Gregorian date into a Julian Day Number, then run the tabular Islamic calendar formula to get the Hijri day, month, and year. It runs offline, returns instantly, and never breaks because a third-party service is down. Here it is, ready to copy:

// Gregorian date -> Hijri (day, month, year)
function toHijri(date, offset) {
  const Y = date.getFullYear(),
        M = date.getMonth() + 1,
        D = date.getDate() - (offset || 0);

  // 1) Gregorian -> Julian Day Number
  let jd = Math.floor((1461 * (Y + 4800 + Math.floor((M - 14) / 12))) / 4)
         + Math.floor((367 * (M - 2 - 12 * Math.floor((M - 14) / 12))) / 12)
         - Math.floor((3 * Math.floor((Y + 4900 + Math.floor((M - 14) / 12)) / 100)) / 4)
         + D - 32075;

  // 2) Julian Day -> Hijri (tabular)
  let l = jd - 1948440 + 10632;
  const n = Math.floor((l - 1) / 10631);
  l = l - 10631 * n + 354;
  const j = (Math.floor((10985 - l) / 5316)) * (Math.floor((50 * l) / 17719))
          + (Math.floor(l / 5670)) * (Math.floor((43 * l) / 15238));
  l = l - (Math.floor((30 - j) / 15)) * (Math.floor((17719 * j) / 50))
        - (Math.floor(j / 16)) * (Math.floor((15238 * j) / 43)) + 29;

  return {
    day:   l - Math.floor((709 * Math.floor((24 * l) / 709)) / 24),
    month: Math.floor((24 * l) / 709),
    year:  30 * n + j - 30
  };
}

// Worldwide ~ offset 1, India/subcontinent ~ offset 2
toHijri(new Date(), 2);  // => { day, month, year }

import math
from datetime import date

def to_hijri(d, offset=0):
    Y, M, D = d.year, d.month, d.day - offset
    # 1) Gregorian -> Julian Day Number
    jd = (math.floor((1461 * (Y + 4800 + (M - 14) // 12)) / 4)
          + math.floor((367 * (M - 2 - 12 * ((M - 14) // 12))) / 12)
          - math.floor((3 * ((Y + 4900 + (M - 14) // 12) // 100)) / 4)
          + D - 32075)

    # 2) Julian Day -> Hijri (tabular)
    l = jd - 1948440 + 10632
    n = (l - 1) // 10631
    l = l - 10631 * n + 354
    j = (((10985 - l) // 5316) * ((50 * l) // 17719)
         + (l // 5670) * ((43 * l) // 15238))
    l = (l - ((30 - j) // 15) * ((17719 * j) // 50)
         - (j // 16) * ((15238 * j) // 43) + 29)

    month = (24 * l) // 709
    return {
        "day":   l - (709 * month) // 24,
        "month": month,
        "year":  30 * n + j - 30,
    }

# Worldwide ~ offset 1, India/subcontinent ~ offset 2
to_hijri(date.today(), offset=2)

Same algorithm, two languages. It ports cleanly to PHP, Swift, Kotlin, Go, anything, because it’s just integer math. This is the same calculation that powers this site.

# The one thing most devs get wrong

The raw tabular formula usually runs a day or two ahead of the dates people actually follow, because real calendars are anchored to moon sighting, not pure arithmetic. The fix is a small fixed regional offset, the offset argument in the code above.

For the Indian subcontinent (India, Pakistan, Bangladesh), the sighting-based date typically sits a day or two behind the raw value, and the worldwide or Saudi date sits one day ahead of the subcontinent. A robust implementation computes both a worldwide and a regional value, the difference between them is exactly the familiar one-day gap your users expect to see.

The full reasoning, the 29 or 30 day rule, the role of moon sighting, is on our How We Determine the Islamic Date page.

# The shape of a converted date

Whatever language you use, model a single date as a Gregorian value paired with its Hijri equivalent and a little metadata. A clean structure:

{
  "gregorian": "2026-02-20",
  "hijri": {
    "day": 1,
    "month": 9,
    "month_name": "Ramadan",
    "year": 1447
  },
  "region": "worldwide"
}

Storing both a worldwide and a regional value per date is what lets you render the one-day difference correctly, the same approach this site uses.

# Open project & reference

We keep a public presence on GitHub with methodology notes and reference material on working with Hijri dates. If you want to follow how the project evolves, or see reference material, that’s the place.

# Who this is for

• App developers adding an Islamic calendar, prayer-time, or event-reminder feature.
• Researchers working with the lunar calendar who need reproducible date math.
• Tinkerers who just want a clean, dependency-free Hijri conversion they own.

If you’re not a developer and just want today’s date, the website and apps are the easier route.

# Accuracy & responsibility

A calculated Hijri date, calibrated to local sighting convention, is accurate to within a day for most regions. Build it into your tools with confidence, but pass on the same honesty we keep: a calculated date is a strong reference, not a religious ruling. For the confirmed start of Ramadan, the Eids, and Hajj, end users should follow their local moon-sighting authority. If your app shows these dates, a short note to that effect serves your users well.

# FAQ