Data API

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"}]
        },
        "special": {"2015-03-08": [{"start": "09:00", "end": "18:00"}],
                    "2015-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). On Sunday 8th March 2015 (08/03/2015) the store will be open from 9:00am to 6:00pm instead of closed. On Monday 9th March 2015 (09/03/2015) 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 falsy, 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.

Resolution rules

  • Check for a special rule
  • Check for an usual day numbered rule
  • Check for a default rule

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:

  • open
  • opening_hours
  • weekly_opening

open

Contains these two properties:

  • open_now : a boolean which tells you if the store is currently open
  • opening_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 brut 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.