Une API REST en lecture seule, en JSON, sans clé ni inscription. La spécification complète est au format OpenAPI 3.1.
https://jours-libres.alpha.my-gardeo.fr/v1. Toutes les requêtes sont des GET.{"data": …, "meta": …}. meta rappelle la requête interprétée, la licence et l'attribution.AAAA-MM-JJ. Elles sont inclusives et exprimées dans le calendrier local de la zone : une période du 17 octobre au 1er novembre comprend ces deux jours.lang (code ISO 639-1 : fr, en, de…) choisit la langue du champ name. Sans lui, l'en-tête Accept-Language décide, puis l'anglais. Quand une traduction manque, l'anglais puis le français la remplacent. Le champ names donne toujours toutes les traductions connues.Un pays est découpé en subdivisions : départements en France, Länder en Allemagne, cantons en Suisse, communautés en Espagne, län en Suède… Chaque subdivision appartient à une zone de vacances scolaires (par exemple FR-ZA, la zone A) et à une zone de jours fériés, c'est-à-dire un régime (par exemple FR-ALSACE-MOSELLE).
Trois façons d'interroger les périodes :
subdivision=FR-D67) : l'API retrouve la zone de vacances et le régime de jours fériés. C'est la façon recommandée.zone=FR-ZB) : directement une zone de vacances ou un régime de jours fériés.nationwide) et, sinon, la liste des zones concernées./v1/countriesListe des pays couverts et, pour chacun, ce que l'API fournit : jours fériés, vacances scolaires, granularité, années et sources.
| Paramètre | Type | Rôle |
|---|---|---|
includeUncovered | booléen | Ajoute les pays ISO sans aucune donnée, avec « available: false ». |
europeanUnion | booléen | Ne garde que les 27 pays de l'Union européenne. |
lang | texte | Langue des noms. |
curl "https://jours-libres.alpha.my-gardeo.fr/v1/countries?europeanUnion=true&lang=fr"/v1/countries/{code}Détail d'un pays : couverture, zones avec leur nombre de subdivisions, textes officiels relevés et limites connues.
| Paramètre | Type | Rôle |
|---|---|---|
lang | texte | Langue des noms. |
curl "https://jours-libres.alpha.my-gardeo.fr/v1/countries/IT"/v1/countries/{code}/subdivisionsSubdivisions sélectionnables d'un pays, avec leur zone de vacances et leur régime de jours fériés.
| Paramètre | Type | Rôle |
|---|---|---|
q | texte | Recherche par nom ou par code, sans accents ni majuscules : « rhone », « 69 », « bayern ». |
lang | texte | Langue des noms. |
curl "https://jours-libres.alpha.my-gardeo.fr/v1/countries/FR/subdivisions?q=rhone"/v1/countries/{code}/zonesZones de vacances scolaires et régimes de jours fériés d'un pays, chacun avec la liste de ses subdivisions.
| Paramètre | Type | Rôle |
|---|---|---|
kind | school ou public | Ne garde qu'un type de zone. |
lang | texte | Langue des noms. |
curl "https://jours-libres.alpha.my-gardeo.fr/v1/countries/FR/zones?kind=school"/v1/public-holidaysJours fériés. Chaque jour indique s'il vaut pour tout le pays et, sinon, les régimes concernés.
| Paramètre | Type | Rôle |
|---|---|---|
country | code ISO, obligatoire | Pays, par exemple FR. |
subdivision | code | Subdivision, par exemple FR-D69 ou DE-BY. |
zone | code | Zone du même type que la liste demandée, à la place d'une subdivision. |
year | AAAA | Une année civile entière. |
from, to | AAAA-MM-JJ | Une plage de dates, à la place de year. 1096 jours au plus. Par défaut : l'année en cours. |
lang | texte | Langue des libellés. |
curl "https://jours-libres.alpha.my-gardeo.fr/v1/public-holidays?country=FR&subdivision=FR-D67&year=2026"/v1/school-holidaysVacances scolaires, regroupées quand plusieurs zones partagent les mêmes dates.
| Paramètre | Type | Rôle |
|---|---|---|
country | code ISO, obligatoire | Pays, par exemple FR. |
subdivision | code | Subdivision, par exemple FR-D69 ou DE-BY. |
zone | code | Zone du même type que la liste demandée, à la place d'une subdivision. |
year | AAAA | Une année civile entière. |
from, to | AAAA-MM-JJ | Une plage de dates, à la place de year. 1096 jours au plus. Par défaut : l'année en cours. |
lang | texte | Langue des libellés. |
curl "https://jours-libres.alpha.my-gardeo.fr/v1/school-holidays?country=FR&from=2026-09-01&to=2027-08-31"/v1/calendarJours fériés et vacances scolaires ensemble, pour un pays ou une subdivision. meta rappelle la zone de vacances, le régime de jours fériés et le fuseau horaire retenus.
| Paramètre | Type | Rôle |
|---|---|---|
country | code ISO, obligatoire | Pays. |
subdivision | code | Subdivision. |
year, from, to | dates | Comme pour les listes. |
lang | texte | Langue des libellés. |
curl "https://jours-libres.alpha.my-gardeo.fr/v1/calendar?country=CH&subdivision=CH-GE&year=2026"/v1/is-holidayDit si une date est fériée ou en vacances. Avec une subdivision, isPublicHoliday et isSchoolHoliday valent pour elle ; sans subdivision, pour tout le pays seulement. Les listes donnent le détail, zones comprises.
| Paramètre | Type | Rôle |
|---|---|---|
country | code ISO, obligatoire | Pays. |
subdivision | code | Subdivision. |
date | AAAA-MM-JJ | Par défaut : aujourd'hui, dans le fuseau de la zone. |
lang | texte | Langue des libellés. |
curl "https://jours-libres.alpha.my-gardeo.fr/v1/is-holiday?country=DE&subdivision=DE-BY&date=2026-08-15"/v1/calendar.icsLes jours fériés et les vacances d'un pays ou d'une subdivision au format iCalendar, pour abonner un agenda. Par défaut : de l'année précédente à l'année suivante. Les événements sont des journées entières, marquées disponibles.
| Paramètre | Type | Rôle |
|---|---|---|
country | code ISO, obligatoire | Pays. |
subdivision | code | Subdivision. |
from, to | AAAA-MM-JJ | Plage personnalisée. |
lang | texte | Langue des titres. |
curl "https://jours-libres.alpha.my-gardeo.fr/v1/calendar.ics?country=FR&subdivision=FR-D69&lang=fr"/v1/export.json.gzToute la base en un fichier JSON compressé, regénéré après chaque synchronisation : pays, subdivisions, zones et périodes, avec leur provenance. C'est la voie à suivre pour tout usage en masse.
curl "https://jours-libres.alpha.my-gardeo.fr/v1/export.json.gz"/v1/sourcesLes sources, leur licence et l'état de leur dernière synchronisation.
curl "https://jours-libres.alpha.my-gardeo.fr/v1/sources"| Champ | Description |
|---|---|
date | Jours fériés seulement : le jour, identique à startDate. |
startDate, endDate | Premier et dernier jour, inclus. |
dayCount | Nombre de jours de la période. |
weekday | Jour de la semaine du premier jour, en anglais : monday… |
name, names | Libellé dans la langue demandée, et toutes ses traductions. |
nationwide | Vrai quand la période vaut pour toutes les zones du pays. |
zones | Codes des zones concernées ; vide quand nationwide est vrai. |
source | Provenance : id, name, license et, pour un texte officiel, document avec son éditeur, son titre et son adresse. |
{
"date": "2026-12-26",
"startDate": "2026-12-26",
"endDate": "2026-12-26",
"dayCount": 1,
"name": "2ème jour de Noël",
"names": {"fr": "2ème jour de Noël"},
"nationwide": false,
"zones": ["FR-ALSACE-MOSELLE"],
"source": {"id": "fr-gouv", "name": "Jours fériés en France", "license": "Licence Ouverte 2.0 (Etalab)", "document": null}
}RateLimit-Limit, RateLimit-Remaining et RateLimit-Policy. Une réponse 429 ajoute Retry-After et RateLimit-Reset, en secondes.Cache-Control) et portent un ETag : renvoyez-le dans If-None-Match pour recevoir un 304, qui compte toutefois dans le quota.| Code | error | Quand |
|---|---|---|
| 400 | invalid_parameter | Paramètre absent ou mal formé ; parameter le nomme. |
| 404 | not_found | Pays, subdivision ou zone inconnus ; resource et identifier les précisent. |
| 405 | method_not_allowed | Autre méthode que GET. |
| 429 | rate_limited | Limite atteinte ; retryAfter donne l'attente en secondes. |
| 503 | export_not_ready | L'export n'a pas encore été généré. |
Les données sont publiées sous Open Database License (ODbL) 1.0, qu'impose l'une des sources, OpenHolidays. Vous pouvez les utiliser, y compris commercialement, à condition de :
Un produit qui se contente d'afficher ces données (une application, un site) n'a pas à être sous ODbL ; seule l'attribution est due. Le détail est sur la page Sources.