Périodes d'ouverture - Le site pour les développeurs Apidae

Les ouvertures (champ ouverture) permettent de déterminer quand un objet touristique est accessible aux visiteurs.

Conseils d’utilisation

En fonction des besoins de votre application, plusieurs informations sont disponibles avec des niveaux de complexité d’exploitation différentes. Il est important de déterminer quels sont les besoins à traiter de manière à exploiter le plus judicieusement possible les informations à disposition.

Le champ à favoriser, sauf besoin plus précis, est le champ periodeEnClair. C’est un champ textuel simple (internationalisé).

En cas de besoin de recherche (quel objet est ouvert tel jour), favorisez l’utilisation du champ datesOuverture (disponible dans les API ou exports) ou des recherches API qui vous fournissent l’information de manière simple en interprétant pour vous les périodes d’ouverture.

N’utilisez l’interprétation des périodes d’ouverture que si cela s’avère nécessaire. Simplifiez-vous la vie avec les champs periodeEnClair ou datesOuverture autant que possible.

> Outils pour l’exploitation des ouvertures

Champ ouverture

Nom du champ	Type	Contenu
ouvertTouteLAnnee	enum	« OUVERT_TOUTE_L_ANNEE » ou rien Sert principalement pour pour gérer la saisie.
fermeTemporairement	enum	« FERME_TEMPORAIREMENT » ou rien Indique si un établissement est fermé. Les périodes d’ouverture classiques restent disponibles.
periodeEnClair	libellé internationalisé	la période en clair
indicationsPeriode	liste d’éléments de référence	Indication sur la saisonnalité. Indication sur des cas particuliers (Fermé le lundi soir, …) Attention : les valeurs été, automne, hiver, printemps sont auto gérées : vous ne pouvez ni les ajouter, ni les supprimer (ignorées silencieusement lors de l’écriture).
ouverturesComplementaires	liste d’éléments de référence	Sert entre autre à la génération automatique du libellé en clair (à la demande, ouvert 24h/24, …)
periodesOuvertures	liste de périodes d’ouverture	Voir la suite
fermeturesExceptionnelles	liste de fermetures exceptionnelles	Voir la suite. Ces informations sont à combiner avec les périodes pour déterminer les jours d’ouverture

Périodes d’ouverture

Les périodes d’ouverture sont stockées dans le champ ouverture.periodesOuvertures.

Les types de période disponibles sont les suivants :

OUVERTURE_TOUS_LES_JOURS : indique que l’objet est ouvert tous les jours sur la période indiquée. Les listes ouverturesJourDuMois et ouverturesJournalieres sont vides.
OUVERTURE_SAUF : indique que l’objet est ouvert tous les jours sur la période indiquée sauf les jours de la semaine indiqués dans la liste ouverturesJournalieres. Si aucune ouverturesJournalieres n’est présente, alors il faut considérer une ouverture tous les jours de la semaine.
OUVERTURE_SEMAINE : indique que l’objet est ouvert seulement les jours de la semaine indiqués dans ouverturesJournalieres sur la période indiquée.
OUVERTURE_MOIS : indique que l’objet est ouvert seulement les jours du mois indiqués dans la liste ouverturesJourDuMois sur la période indiquée.

Si le booléen tousLesAns est à true, les années présentes dans les dates ne doivent pas être prises en compte. Les dates restent valable sur toutes les années, celle en cours, celle à venir, etc.

Nom du champ	Type	Contenu
nom	libellé internationalisé	non utilisé
complementHoraire	libellé internationalisé	Complément d’informations sur la période d’ouverture
dateDebut	date	début de la période, date inclue dans la période.
dateFin	date	fin de la période, inclus dans la période.
horaireOuverture	heure	heure d’ouverture, peut être absent.
horaireFermeture	heure	heure de fermeture ; peut être absent.
type	enum	Voir liste ci-dessus.
tousLesAns	booléen	Indique si la période est à prendre en compte tous les ans.Dans ce cas, l’année indiquée pour les débuts et fins de périodes ne sont pas significatives. Il faut considérer que la période s’applique de manière continuelle.
ouverturesJournalieres	Voir la suite	seulement pour les OUVERTURE_SAUF et OUVERTURE_SEMAINE
ouverturesJourDuMois	Voir la suite	seulement pour les OUVERTURE_MOIS
ouverturesExceptionnelles	Voir la suite
identifiantTechnique	entier	identifiant unique correspondant à la version de saisie de la tranche horaire

Ouverture jour du mois

L’ouverture jour du mois permet de définir les jours du mois concernés par une période OUVERTURE_MOIS.

Nom du champ	Type	Contenu
jourDuMois	enum	Permet de définir quel est le jour du mois concerné (exemple : Lundi et D_1ER = le premier lundi du mois)D_1ER : premierD_2EME : deuxièmeD_3EME : troisièmeD_4EME : quatrièmeD_DERNIER : dernier
jour	enum	LUNDI, MARDI, MERCREDI, JEUDI, VENDREDI, SAMEDI, DIMANCHE

Ouverture journalière

L’ouverture jour du mois permet de définir les jours du mois concernés par une période OUVERTURE_SAUF ou OUVERTURE_SEMAINE.

Nom du champ	Type	Contenu
jour	enum	LUNDI, MARDI, MERCREDI, JEUDI, VENDREDI, SAMEDI, DIMANCHE, TOUS

Fermeture exceptionnelle

Nouveauté ! Les dates des jours fériés sont à présent renvoyées dans le JSON. Ne sont renvoyées que les dates comprises dans les périodes d’ouvertures saisies.

Nom du champ	Type	Contenu
dateFermeture	date	null si dateSpeciale. Sinon la date de fermeture exceptionnelle au format YYYY-MM-DD
dateSpeciale	enum	null si dateFermeture présente. Sinon :PREMIER_JANVIER, BERCHTOLDSTAG : (suisse) 2 janvier, ARRIVEE_EVANGILE, SAINT_JOSEPH : (suisse) 19 mars, VENDREDI_SAINT, LUNDI_PAQUES, ASCENSION, LUNDI_PENTECOTE, PREMIER_MAI, HUIT_MAI, FETE_AUTONOMIE, QUATORZE_JUILLET, FETE_DIEU (suisse), FETE_NATIONALE_SUISSE : (suisse) 1er août, QUINZE_AOUT, LUNDI_DU_JEUNE_FEDERAL (suisse), FETE_CITOYENNETE, PREMIER_NOVEMBRE, ONZE_NOVEMBRE, IMMACULEE_CONCEPTION : (suisse) 8 décembre, VINGT_CINQ_DECEMBRE, MARDI_GRAS, MERCREDI_DES_CENDRES, JEUDI_MI_CAREME, FETE_VICTOR_SCHOELCHER, JOUR_DES_DEFUNTS, ABOLITION_DE_LESCLAVAGE_GUADELOUPE, ABOLITION_DE_LESCLAVAGE_MARTINIQUE
dates	array	null si dateFermeture. Sinon, renvoie le tableau des échéances pour une date spéciale au format YYYY-MM-DD.

Exemple de JSON renvoyé pour des fermetures exceptionnelles :

{
...
    "ouverture": {
        ...
        "fermeturesExceptionnelles": [
            {
                "dateSpeciale": "HUIT_MAI",
                "dates": [
                    "2025-05-08", 
                    "2026-05-08"
                ]
            },
            {
                "dateFermeture": "2025-04-26" 
            }
        ],
    ...
    }
}

Ouverture exceptionnelle

L’ouverture exceptionnelle s’applique à une période. Elle permet de spécifier un jour d’ouverture de manière individuelle.

Nom du champ	Type	Contenu
dateOuverture	date	la date d’ouverture au format yyyy-mm-dd