Source: https://developers.woosmap.com/products/stores-api/concepts/opening-hours/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Opening Hours ## What Opening Hours Define Opening hours are optional data you add to stores via the `openingHours` property. Once set, the API computes `open_now` in real-time based on the asset's timezone and your rules. There are three layers to the system: - **Usual hours** – A weekly schedule. Define hours per day of the week, plus a `default` fallback. - **Special hours** - Date-specific overrides (e.g. holiday hours or closures). - **Temporary closures** – Date ranges where the store is closed. When resolving whether a store is open, the API checks in this order: 1. Is there an active **temporary closure**? If yes, the asset is closed. 2. Is there a **special** rule for today's date? If yes, use it. 3. Is there a **usual** rule for today's day number? If yes, use it. 4. Is there a **default** rule? If yes, use it. 5. If none of the above match, the asset is considered closed. ## Describing an Asset and Its Opening Hours Here's a full example of an asset with opening hours configured: ```json { "storeId": "123456", "name": "An awesome store Name", "location": { "lat": 48.858093, "lng": 2.294694 }, "openingHours": { "timezone": "Europe/Paris", "usual": { "7": [], "6": [{ "all-day": true }], "default": [{ "start": "08:30", "end": "19:30" }] }, "temporary_closure": [ { "start": "2025-05-19", "end": "2025-05-23" }, { "start": "2025-05-26", "end": "2025-05-28" } ], "special": { "2025-03-07": [{ "start": "09:00", "end": "18:00" }], "2025-03-08": [] } } } ``` This defines an asset named `An awesome store Name` located in Paris, with the following schedule: - **Default hours** open from `8:30am` to `7:30pm` every day not otherwise specified. - **Saturdays** open all day (`all-day: true`). - **Sundays** closed (empty array `[]`). - **Temporary closures** closed from _Monday 19th May 2025_ to _Friday 23rd May 2025_, and from _Monday 26th May 2025_ to _Wednesday 28th May 2025_. - **Special hours** on _Friday 7th March 2025_, open from `9:00am` to `6:00pm` instead of the default. On _Saturday 8th March 2025_, closed all day. ### Timezone The `timezone` field determines how `open_now` is computed. Opening hours are evaluated against the asset's local time, not the requester's. For a complete list of supported values, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) on Wikipedia. ### Hours Hours are defined with a 24-hour format. Each time slice needs a `start` and `end`: ```json { "start": "08:00", "end": "12:00" } ``` The API supports crossing midnight (e.g., `"start": "22:00", "end": "02:00"`): it will correctly compute `open_now` by checking whether the previous day's slice is still active. Alternatively, you can split across two days for clarity: - Day 5 (Friday): `{"start": "20:00", "end": "23:59"}` - Day 6 (Saturday): `{"start": "00:00", "end": "02:00"}` You can also define multiple slices per day for split schedules (e.g., lunch and dinner service): ```json { "5": [ { "start": "11:30", "end": "14:00" }, { "start": "18:00", "end": "23:59" } ] } ``` ### All-day If your store is open 24 hours a day, use `all-day: true`: ```json [{ "all-day": true }] ``` `all-day` cannot be `false`, just omit the property if you don't need it. ### Usual Opening Hours The `usual` object defines the weekly schedule. It accepts the following keys: | Day | Key | | --------- | --- | | Monday | 1 | | Tuesday | 2 | | Wednesday | 3 | | Thursday | 4 | | Friday | 5 | | Saturday | 6 | | Sunday | 7 | The `default` key applies to any day without an explicit entry. For example, if you only define `"7": []` and `"default": [{"start": "09:00", "end": "18:00"}]`, the store is open 9 to 6 Monday through Saturday and closed on Sundays. ### Special Opening and Closing Hours Special hours override the usual schedule for a specific date. The format is the same as usual hours, but keys are dates in `YYYY-MM-DD` format (see [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Dates)). The dashed date format is the only supported format. ### Temporary Closure The `temporary_closure` key defines date ranges where the asset is closed. Each entry has a `start` date (first day of closure) and `end` date (last day of closure), both inclusive. ```json { "temporary_closure": [{ "start": "2025-05-19", "end": "2025-05-23" }] } ``` Temporary closures take priority over all other rules, even special hours for the same date. ## API Response When the API returns an asset, three opening-hours-related objects appear in its properties. See the [API Reference](/api-reference/data-api/post-stores/) for a complete example. - `open`: real-time status - `opening_hours`: the raw rules you provided - `weekly_opening`: computed 7-day schedule ### open Contains the following properties: - `open_now`: a boolean indicating whether the store is currently open. - `open_hours`: an array of time slices for the current day. - `week_day`: the current day of the week (1 = Monday, 7 = Sunday). Depending on the store's current state, you'll also get `current_slice` or `next_opening`. #### current_slice Present when the store is currently open. Contains the active time slice (if the store has multiple slices today, only the current one is returned): ```json { "open": { "open_now": true, "week_day": 1, "current_slice": { "start": "08:00", "end": "12:00" }, "open_hours": [ { "start": "08:00", "end": "12:00" }, { "start": "14:00", "end": "18:00" } ] } } ``` #### next_opening Present when the store is currently closed. Contains the next upcoming time slice and the corresponding `day`. If no opening hours can be found within the next 6 days, `next_opening` is absent. Currently closed, reopening soon: ```json { "open": { "open_now": false, "week_day": 2, "next_opening": { "start": "08:00", "end": "12:00", "day": "2025-02-13" }, "open_hours": [ { "start": "08:00", "end": "12:00" }, { "start": "14:00", "end": "18:00" } ] } } ``` Closed for more than 6 days (e.g., during a temporary closure): ```json { "open": { "open_now": false, "open_hours": [] } } ``` ### opening_hours Contains the raw opening hour data you provided to the API for this asset (timezone, usual, default, special, and temporary closure rules). ### weekly_opening A computed schedule for the **current ISO week (Monday to Sunday)**, based on the asset's rules and taking into account special hours. Each day is keyed by its weekday number (`"1"` = Monday through `"7"` = Sunday), and contains an array of `hours` plus an `isSpecial` flag indicating whether special hours apply for that day. Days that fall within a `temporary_closure` period return `{ "hours": [], "isSpecial": true }`. ```json { "weekly_opening": { "1": { "hours": [], "isSpecial": false }, "2": { "hours": [{ "start": "08:30", "end": "19:30" }], "isSpecial": false }, "3": { "hours": [{ "start": "08:30", "end": "19:30" }], "isSpecial": false }, "4": { "hours": [{ "start": "08:30", "end": "19:30" }], "isSpecial": false }, "5": { "hours": [{ "start": "08:30", "end": "19:30" }], "isSpecial": false }, "6": { "hours": [{ "start": "09:00", "end": "18:00" }], "isSpecial": true }, "7": { "hours": [], "isSpecial": false }, "timezone": "Europe/Paris" } } ``` ## Using Opening Hours in Search The `open` property is included automatically in [Search](/products/stores-api/features/search/) and [Autocomplete](/products/stores-api/features/autocomplete/) responses. You don't need to request it separately. Every asset in the results comes with its real-time opening status. You can use `open_now` client-side to filter or sort your results. For example, showing only currently open stores first: ```javascript const results = response.features; // Filter to only open stores const openStores = results.filter((f) => f.properties.open.open_now); // Or sort: open stores first, then closed results.sort((a, b) => b.properties.open.open_now - a.properties.open.open_now); ``` ## Related - [Data Management](/products/stores-api/features/data-management/) – where you set opening hours on your assets - [Search](/products/stores-api/features/search/) – where you consume opening status in query results - [API Reference](/api-reference/data-api/post-stores/) - complete data model and response examples