Details

Last Updated: 24 November 2024

The Islamic Hijri Date Application Programming Interface (API) used to generate the current Hijri date on our Moon Sighting UK website is based on the actual sighting of the moon by the human eye. It is a unique API of its kind as it is based on the actual visibility of the moon and not on the calculated birth (or non-visibility) of the moon, which is widely used by many other websites and mobile phone apps.

It has been updated with an API Key for reliability and security purposes. Any UK website/app developer can obtain an API Key by completing the Membership Registration form (request it in the comments box) and paying the subscription fee.

The documentation below shows how to use the ICOUK Hijri Date API in several formats, including HTML, and JSON. We highly recommend website designers use the JSON format as it will be supported in the future. It can be used by popular Content Management Systems (CMS), such as Joomla or WordPress.

It is easy to implement on any website, app, software, or anything that can read remote data. Note that the API security from 2024 requires a Bearer Token Authentication (100 characters) method to use the API links below.

The Hijri Date API is here:
https://www.moonsighting.org.uk/api/index.php/v1/hijri?country=UK&return=html

For the JSON format, use the version below:
https://www.moonsighting.org.uk/api/index.php/v1/hijri?country=UK&return=json

The JSON data returned format is here:

{"gregorian":["Sunday","25th","March","2018"],"islamic":["Ahad","7","Rajab","1439"]}

Using the CSS return method (to be tested):
The CSS returns a full HTML pre-formatted with CSS class names. You only need to create the CSS to format it however you want.

<style type="text/css>
	.islamic_date_container{
        display: block;
        border: solid 1px #aaa;
        background-color: #f6f6f6;
        padding: 10px;
        text-align: center;
        font-family: Verdana, Geneva, sans-serif;
        width: 150px;
    }
    
    .islamic_day{ font-size: 11px; line-height: 18px; }
    .islamic_date{ font-weight: bold; color: #777; font-size: 40px; display: block; }
    .islamic_month{ display: block; padding: 5px; }
    .islamic_year{ font-weight: bold; }
    
    .greg_date_container{ display: none; } /* We'll just ignore the gregorian date */
</style>
https://www.moonsighting.org.uk/api/index.php/v1/hijri?country=UK&return=css

Using JSON to format in PHP:

$json = file_get_contents("https://www.moonsighting.org.uk/api/index.php/v1/hijri?country=UK&return=json");
if($json){
	$hijri_data = json_decode($json, true);
	$islamic_day = $hijri_data['islamic'][0];
	$islamic_date = $hijri_data['islamic'][1];
	$islamic_month = $hijri_data['islamic'][2];
	$islamic_year = $hijri_data['islamic'][3];
	
	//do as you wish here with the date (example on next line)
	echo "$islamic_day $islamic_date $islamic_month $islamic_year";
}

For other formats (HTML, CSV, CSS), replace the return parameter according as shown below:
hijri.php?return=html; hijri.php?return=csv; hijri.php?return=css

If you wish to check a future Hijri date for test purposes, then use the date parameter as shown below:
https://www.moonsighting.org.uk/api/index.php/v1/hijri?country=UK&return=json&&date=2018-06-15

The data returned format is here:

{"gregorian":["Friday","15th","June","2018"],"islamic":["Jumuah","1","Shawwal","1439"]}

Note that a separate Hijri Calendar API is also available using a similar API Key method.

The Hijri Calendar API is here:
https://www.moonsighting.org.uk/api/index.php/v1/hijristart?return=json&hijriyear=1438

The data returned format is here:

{"hijrimonths":[
{"year":"1438","month":"1","start_date":"2016-10-03","days":"29","country":"GB"},
{"year":"1438","month":"2","start_date":"2016-11-01","days":"30","country":"GB"},
{"year":"1438","month":"3","start_date":"2016-12-01","days":"30","country":"GB"},
{"year":"1438","month":"4","start_date":"2016-12-31","days":"30","country":"GB"},
{"year":"1438","month":"5","start_date":"2017-01-30","days":"29","country":"GB"},
{"year":"1438","month":"6","start_date":"2017-02-28","days":"30","country":"GB"},
{"year":"1438","month":"7","start_date":"2017-03-30","days":"29","country":"GB"},
{"year":"1438","month":"8","start_date":"2017-04-28","days":"29","country":"GB"},
{"year":"1438","month":"9","start_date":"2017-05-27","days":"30","country":"GB"},
{"year":"1438","month":"10","start_date":"2017-06-26","days":"29","country":"GB"},
{"year":"1438","month":"11","start_date":"2017-07-25","days":"29","country":"GB"},
{"year":"1438","month":"12","start_date":"2017-08-23","days":"30","country":"GB"}
],"msg":"success"}

By using the above Hijri Month start date and the Arabic Names of the months (e.g. from the Islamic Calendar on Wikipedia) it is possible to produce a monthly calendar shown on the Home Page of the Moon Sighting UK website.

Website developers must ensure that the API Keys (bearer tokens) supplied to them are only used for the intended website. An example PHP code for including in the header template/theme of Joomla/WordPress websites is given below:

<?php
 $url = IcoukHelper::ICOUK_API_URL;
 $url = $url.'/hijri?return=html&country=UK';
 $data  = IcoukHelper::requestIcoukApi($url);
 echo $data;
?>

Note that the default country for the ICOUK Hijri Date API is the UK (country=UK), although we have received requests to add additional API for a few other countries. The bearer token (100 characters) is included in the ICOUK_API_URL file path.

Related: ICOUK Hijri Calendar Widgets

---

If you have any comments or questions regarding this article, please do not hesitate to email us via our online Contact Us form.