Opening Hours

How Woosmap handles your store opening hours, including timezone, usual, special, and temporary closure rules.

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 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).

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 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 and 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 – where you set opening hours on your assets
• Search – where you consume opening status in query results
• API Reference - complete data model and response examples

‹ Query Syntax Map JS StoresService ›

Was this helpful?

Failed to send feedback. Please try again.

Thanks for your feedback!