Opening Hours
Woosmap handles your store opening hours
Describing an asset and its opening hours
{
"storeId": "aGkgdGhlcmUsIGZvdW5kIHNvbWV0aGluZyBuaWNlID8K",
"name": "An awesome store Name",
"location": {
"lng": 2.294694,
"lat": 48.858093
},
"openingHours": {
"timezone": "Europe/Paris",
"usual": {
"7": [],
"6": [{"all-day": true}],
"default": [{"start": "08:30", "end": "19:30"}]
},
"temporary_closure": [{"start": "2024-05-20", "end": "2024-05-24"},{"start": "2024-05-27", "end": "2024-05-29"}],
"special": {"2024-03-08": [{"start": "09:00", "end": "18:00"}],
"2024-03-09": []
}
}
Defines an asset named An awesome store Name located in Paris.
This store is closed on Sundays, open all day on saturday, and is open from 8:30 to 19:30 (8:30am to 7:30pm).
From Monday 20th May 2024 to Friday 24th May 2024 the store will be temporary closed.
From Monday 27th May 2024 to Wednesday 29th May 2024 the store will be temporary closed.
On Friday 8th March 2024 (08/03/2024) the store will be open from 9:00am to 6:00pm instead of closed.
On Sunday 9th March 2024 (09/03/2024) the store will be closed all day.
Timezone
Defines opening hours in the Europe/Paris timezone. It is used to compute the open_now property of an asset.
For a more complete list of possible timezone values see List of tz database time zones article on Wikipedia.
Hours
The hours are defined in 24 hour format, and to define a slice of time where the store is open you must define a start, end keys.
start, end must belong to the same day (crossing midnight may result in open_now being always false.)
{ "start": "08:00", "end": "12:00" }
All-day
If you want to declare your store is open 24 hours a day, use all-day: true.
all-day cannot be false, just don’t pass this property if you don’t need it.
Usual opening hours
usual: may contain the following keys "1", "2", "3", "4", "5", "6", "7", "default"
| Day | Week day |
|---|---|
| Monday | 1 |
| Tuesday | 2 |
| Wednesday | 3 |
| Thursday | 4 |
| Friday | 5 |
| Saturday | 6 |
| Sunday | 7 |
The default applies when no explicit hours are defined for the current day.
Special opening and closing hours
The format for defining opening and closing hours for a particular day is the same as the usual. Instead of using numeric week day for keys you must use a date YYYY-MM-DD (see ISO-8601).
The dashed date is the only supported format.
Temporary closure
You can defined temporary closed periods with the temporary_closure key. Composed of a start date (first included day of closure) and end date (last included day of closure). Once defined, those periods are used to compute open_now value and weekly_opening.
Resolution rules
- Check for a
specialrule - Check for a
usualday numbered rule - Check for a
defaultrule
If one of the above rules match, the store will be considered open, else closed.
API Response
When the API returns an asset’s json, you will find three objects in its properties. See the sample API Response for a complete example:
openopening_hoursweekly_opening
open
Contains these two properties:
open_now: a boolean which tells you if the store is currently openopening_hours: an array of opening hour slices for the current day
And depending on the store current opening state, current_slice and next_slice.
current_slice property
The current_slice property contains the current opening hours. (if the store has multiple opening hours slice, only the current slice will be returned).
Example of a currently open store:
{
"open": {
"open_now": true,
"current_slice": { "start": "08:00", "end": "12:00" },
"opening_hours": [
{ "start": "08:00", "end": "12:00" },
{ "start": "14:00", "end": "18:00" }
]
}
}
next_slice property
The next_slice property contains next opening hour slice and corresponding day.
When no future opening hours can be found within 6 days, the store will be considered closed and next_slice will be false.
Example of a currently closed store:
{
"open": {
"open_now": false,
"next_slice": { "start": "08:00", "end": "12:00", "day": "2016-02-13" },
"opening_hours": [
{ "start": "08:00", "end": "12:00" },
{ "start": "14:00", "end": "18:00" }
]
}
}
Example of an asset that is closed for more than 6 days:
{
"open": {
"open_now": false,
"next_slice": false,
"opening_hours": []
}
}
opening_hours
It contains the initial opening hour data you provided to the API for this store (Timezone, usual, default, special…)
weekly_opening
It contains opening hours for the current week.
