Ghroubi API v1

Overview

All requests are GET and return UTF-8 JSON. Responses are wrapped in a consistent envelope and cached for 5 minutes (Cache-Control). The API is cross-origin enabled (CORS).

Base URL

https://grobi.misoor.com/api/v1

Response envelope

Every successful response includes the API version, a generation timestamp, then the data.

{
  "api_version": "1.0",
  "generated_at": "2026-06-28T09:00:00+00:00",
  "count": 1,
  "events": [ /* ... */ ]
}

Authentication

Currently open

The API is open with no key. A key mode may be enabled later — check the requires_api_key field in the meta endpoint. When enabled, send your key in one of two ways:

# Query parameter
GET https://grobi.misoor.com/api/v1/events.php?country=sa&api_key=YOUR_KEY

# HTTP header
X-API-Key: YOUR_KEY

Events

Returns confirmed Hijri events. All parameters are optional and can be combined.

Example request

https://grobi.misoor.com/api/v1/events.php?country=sa&upcoming=1&limit=5

Example response

{
  "api_version": "1.0",
  "generated_at": "2026-06-28T09:00:00+00:00",
  "count": 1,
  "events": [
    {
      "country": { "code": "sa", "name_ar": "السعودية", "name_en": "Saudi Arabia" },
      "event":   { "type": "ramadan", "label_ar": "دخول شهر رمضان", "label_en": "Start of Ramadan" },
      "hijri_year": 1448,
      "gregorian_date": "2027-02-17",
      "note": null,
      "mode": "manual",
      "published_at": "2026-06-28 09:00:00"
    }
  ]
}

Countries

Returns all supported countries with Arabic and English names and each country code (used in the country param and as the notification topic).

{
  "api_version": "1.0",
  "count": 13,
  "countries": [
    { "code": "ae", "name_ar": "الإمارات", "name_en": "United Arab Emirates" },
    { "code": "sa", "name_ar": "السعودية", "name_en": "Saudi Arabia" }
    /* ... */
  ]
}

Meta

A self-describing endpoint: returns the event types with their labels and descriptions, the API status (does it require a key now?), and the list of endpoints.

{
  "api_version": "1.0",
  "requires_api_key": false,
  "event_types": [
    { "type": "ramadan", "label_ar": "دخول شهر رمضان",
      "label_en": "Start of Ramadan", "description_en": "Confirmed sighting of the Ramadan crescent." }
    /* ... */
  ],
  "endpoints": { /* ... */ }
}

Branding & attribution

If you use Ghroubi data in your app, show a “Powered by Ghroubi” badge to your users and link it to the Ghroubi site. Two ways: a ready-made SVG badge (easiest), or branding assets via JSON to build it inside native apps.

1) Ready-made badge (one line)

<!-- HTML -->
<a href="https://grobi.misoor.com">
  <img src="https://grobi.misoor.com/api/v1/badge.php?lang=ar&theme=dark" alt="بيانات من غروبي" height="38">
</a>

2) Branding assets (JSON)

For native apps (Flutter, etc.): logo URLs (SVG), attribution text in Arabic and English, brand colors, and ready-to-use embed snippets.

{
  "attribution": { "text_ar": "بيانات من غروبي", "text_en": "Powered by Ghroubi", "url": "https://grobi.misoor.com" },
  "logo":  { "mark": "…/assets/mark.svg", "full": "…/assets/logo.svg", "full_dark": "…/assets/logo-dark.svg" },
  "badge": { "ar_dark": "…/badge.php?lang=ar&theme=dark" /* … */ },
  "colors": { "brand": "#7a3aa0", "brand2": "#ff7a45" },
  "guidelines": { /* لا تُعِد تلوين الأيقونة / don't recolor the mark */ }
}

Event types

Event object fields

Errors

On error, an appropriate HTTP status and a consistent JSON body are returned:

{
  "api_version": "1.0",
  "error": { "code": "bad_country", "message": "Invalid country code." }
}

Code examples

curl "https://grobi.misoor.com/api/v1/events.php?country=sa&upcoming=1"

# with API key (only if key mode is enabled)
curl -H "X-API-Key: YOUR_KEY" "https://grobi.misoor.com/api/v1/events.php?country=sa"

const res  = await fetch("https://grobi.misoor.com/api/v1/events.php?country=sa&upcoming=1");
const data = await res.json();
console.log(data.events);
// data.events[0].event.label_en  ->  "Start of Ramadan"

import 'package:http/http.dart' as http;
import 'dart:convert';

final res  = await http.get(Uri.parse(
    'https://grobi.misoor.com/api/v1/events.php?country=sa&upcoming=1'));
final data = jsonDecode(res.body);
print(data['events']);

$url  = "https://grobi.misoor.com/api/v1/events.php?country=sa&upcoming=1";
$data = json_decode(file_get_contents($url), true);
print_r($data['events']);