API Reference

Holidays & Operating Status

Country/city holiday calendars and holiday-aware place open status.

Holidays & Operating Status

Fetch a country's (or city's) holiday calendar, ask which holiday is in effect right now, and let place cards reflect holiday hours automatically.

Scope required: places

Why this matters in MENA. Across Jordan, Saudi Arabia, the UAE and the wider region, opening hours bend around the calendar far more than in the West. The two Eids shift every year on the lunar calendar; national days and bank holidays close offices and government services; and Fridays (plus holiday eves) routinely run shortened or split hours. A static "open until 23:00" is often wrong during Eid. These endpoints give you a single, timezone-correct source of truth so your app can say "Open · Eid al-Fitr · hours may vary" instead of confidently showing the wrong time.

All times are resolved in the target country's own timezone (e.g. Asia/Amman for JO, Asia/Riyadh for SA, Asia/Dubai for AE), not the caller's clock.

GET /holidays

The full holiday calendar for a country, optionally narrowed to a city and/or a date window.

Scope required: places

curl -s "https://navvo.io/api/v1/holidays?country=JO&from=2026-01-01&to=2026-12-31" \
  -H "x-api-key: nvvo_YOUR_KEY"

Query parameters

country

string

ISO-3166-1 alpha-2 country code (e.g. JO, SA, AE). Defaults to JO.

city

string

Optional city name to include city-specific observances in addition to national ones. Omit for the whole country.

from

string

Inclusive start date (YYYY-MM-DD). Filters which dated/expanded holidays are returned.

string

Inclusive end date (YYYY-MM-DD).

Response

An array of holiday objects:

[
  {
    "id": "jo-independence-day",
    "countryCode": "JO",
    "city": null,
    "name": "Independence Day",
    "nameAr": "عيد الاستقلال",
    "type": "national",
    "recurring": true,
    "month": 5,
    "day": 25,
    "date": "2026-05-25",
    "affectsBusinessHours": true,
    "enabled": true
  },
  {
    "id": "jo-eid-al-fitr-2026",
    "countryCode": "JO",
    "city": null,
    "name": "Eid al-Fitr",
    "nameAr": "عيد الفطر",
    "type": "religious",
    "recurring": false,
    "month": null,
    "day": null,
    "date": "2026-03-20",
    "affectsBusinessHours": true,
    "enabled": true
  }
]

Field	Type	Description
`id`	string	Stable identifier for the holiday entry.
`countryCode`	string	ISO alpha-2 country the holiday belongs to.
`city`	string \| null	City name when the holiday is city-specific, else `null` (nationwide).
`name`	string	English display name.
`nameAr`	string	Arabic display name.
`type`	string	One of `public`, `religious`, `bank`, `national`, `observance`.
`recurring`	boolean	`true` for fixed-date holidays that repeat every year (use `month`/`day`); `false` for moving holidays (use `date`).
`month`	number \| null	Calendar month `1`–`12` for recurring holidays; `null` for moving holidays.
`day`	number \| null	Day of month for recurring holidays; `null` for moving holidays.
`date`	string \| null	Absolute `YYYY-MM-DD` date. Always set for moving holidays; for recurring holidays it is the resolved date within the requested window.
`affectsBusinessHours`	boolean	Whether this holiday should change how open/closed status is shown.
`enabled`	boolean	Whether the entry is active. Disabled entries are normally omitted.

Recurring vs. moving. Fixed-date holidays (national days, New Year's Day) have recurring: true and are keyed by month/day, so they repeat yearly. Lunar / moving holidays — the two Eids, the Islamic New Year, Prophet's Birthday — have recurring: false and carry an absolute date for the specific year, because their Gregorian date shifts. When you pass from/to, recurring holidays are expanded to concrete dates inside that window so every returned object has a usable date.

GET /holidays/today

The single holiday in effect right now (or at a supplied instant) for a country/city. Ideal for a quick banner or for deciding whether to annotate opening hours.

Scope required: places

curl -s "https://navvo.io/api/v1/holidays/today?country=JO" \
  -H "x-api-key: nvvo_YOUR_KEY"

# Check status at a specific instant (ISO 8601)
curl -s "https://navvo.io/api/v1/holidays/today?country=AE&city=Dubai&at=2026-12-02T09:00:00Z" \
  -H "x-api-key: nvvo_YOUR_KEY"

Query parameters

country

string

ISO alpha-2 country code. Defaults to JO.

city

string

Optional city, to pick up city-specific observances.

string

Optional ISO 8601 instant to evaluate instead of now (e.g. 2026-03-20T08:00:00Z). The instant is converted into the country's timezone before matching, so a date sits on the right local day.

Response

{
  "country": "JO",
  "city": null,
  "holiday": {
    "name": "Eid al-Fitr",
    "nameAr": "عيد الفطر",
    "type": "religious",
    "affectsBusinessHours": true
  }
}

When no holiday is active, holiday is null:

{
  "country": "JO",
  "city": null,
  "holiday": null
}

Field	Type	Description
`country`	string	The resolved country code.
`city`	string \| null	The resolved city, or `null` if none was requested.
`holiday`	object \| null	The active holiday (`name`, `nameAr`, `type`, `affectsBusinessHours`), or `null` if today is an ordinary day.

Use affectsBusinessHours to decide whether to surface a "hours may vary" hint. A holiday can be present (e.g. an observance) without changing business hours — in that case you might show the name but keep normal hours.

GET /holidays/on

Is a specific date a holiday? — for "will this be open next Thursday?" planning. Resolves both recurring (month/day) and absolute-date holidays in the country's timezone.

?date=YYYY-MM-DD&country=JO&city=

curl -s "https://navvo.io/api/v1/holidays/on?date=2026-12-25&country=JO" \
  -H "x-api-key: $NAVVO_API_KEY"

{ "provider": "navvo-holidays", "country": "JO", "date": "2026-12-25",
  "isHoliday": true,
  "holiday": { "name": "Christmas Day", "nameAr": "عيد الميلاد المجيد", "type": "religious", "affectsBusinessHours": true } }

An ordinary day returns isHoliday: false and holiday: null. A malformed date returns isHoliday: false with an error.

GET /holidays/upcoming

The holidays in the next N days — recurring holidays are resolved to their next occurrence, absolute-date ones included if they fall in the window, sorted soonest-first with daysUntil.

?country=JO&days=30&city=

{
  "provider": "navvo-holidays", "country": "JO",
  "from": "2026-06-27", "to": "2027-06-27", "days": 365, "count": 4,
  "holidays": [
    { "date": "2026-12-25", "daysUntil": 181, "name": "Christmas Day", "type": "religious", "affectsBusinessHours": true, "city": null },
    { "date": "2027-01-01", "daysUntil": 188, "name": "New Year's Day", "type": "public", "affectsBusinessHours": true, "city": null }
  ]
}

Field	Type	Notes
`from` / `to`	string	the resolved date window
`holidays[].date`	string	the resolved occurrence date (`YYYY-MM-DD`)
`holidays[].daysUntil`	number	days from today to that holiday

Holiday-aware place status

You don't have to wire holidays into your place cards yourself — Navvo does it for you. Both GET /places/{slug} and GET /places/thumb now include a holiday field and annotate openText when an active holiday affects business hours.

The holiday field uses the same shape as /holidays/today's holiday:

{
  "url": "https://navvo.io/uploads/abc123.webp",
  "source": "logo",
  "rating": 4.6,
  "openState": "open",
  "openText": "Open · until 23:00 · Eid al-Fitr · hours may vary",
  "holiday": {
    "name": "Eid al-Fitr",
    "nameAr": "عيد الفطر",
    "type": "religious",
    "affectsBusinessHours": true
  }
}

How it behaves:

The place's country/city (and its timezone) determine which calendar is consulted — the same logic as /holidays/today.
When an active holiday has affectsBusinessHours: true, openText is suffixed with · {holiday name} · hours may vary so the card communicates that posted hours are uncertain during the holiday.
The structured holiday object is always returned alongside, so you can render your own badge (and pick name vs. nameAr for the user's locale) instead of parsing openText.
On an ordinary day, holiday is null and openText is unchanged.

It never hard-closes a place. Holiday awareness is advisory only. openState continues to be computed from the place's posted opening hours; the holiday annotation simply warns that those hours may vary. Navvo will not flip a place to closed purely because it's a public holiday — many cafes, malls and pharmacies stay open (often on special Eid hours), so the truthful signal is "hours may vary," not "closed."

Errors

Status	When
`400`	Validation (e.g. malformed `from`/`to`/`at`).
`401` / `403`	Missing/invalid key, or key lacks the `places` scope.

Addressing

Plus Code addressing for the MENA region — encode, decode, and resolve shareable offline-derivable addresses, plus fault-tolerant Arabic autocomplete.

EV Charging & Range Routing

Charging-station discovery and battery-range-aware route planning with charge stops.