Accessing Hours

The opening hours is a crucial part of place information. This information can be used to plan a visit to the venue in advance, such as determining the next time the venue is open, or a future series of dates such as when the user wishes to visit.

When considering presenting opening hours to a user, you should observe several key user interface considerations:

• Multiple open/closed intervals can occur per day
• Venues can be open always/24H, open late or closed all day
• Public holidays can affect regular trading hours
• Some open/closed times can be restricted (provide space for a comment)
• Time zones can be critical for local visitors or distant travellers trying to contact the operator

Note: The source/provider of opening hours can affect the quality of the opening hours, and how up to date the information may be. It is generally recommended that you suggest to users to check the official opening hours with the operator.

Opening Hours

Various place providers engage operators to contribute their opening hours. These are made accessible through the API in order for you to present to the user.

• Use forDays() to query a range of dates for opening hours for a place. Use this to present a weeks worth of opening hours, or possibly more (such as a calendar).
• Use intervals() to access the next series of opening hours for a place. Use this to present the immediate open/closed times
• Use osmTag field to return a single string representation of the opening hours encoded in a way that can be parsed, according to using Open Street Map opening hours specification.

Open/Closed hours for a specific date range using forDays() operation

The forDays() operation allows you to define a date range, such as for the next day, week or future calendar range. For each of the dates that are selected, you will be provided the intervals() operations to access the open/closed window intervals.

1# Obtain the open/closed hours for the place given a period, such as the
2# upcoming week or future date range. Includes information on local public
3# holidays that could affect opening hours.
4
5query QueryDateRangeOpenClosedTimes {
6  # Use the place() operation
7  place(id: "place/facebook:page:mavisthegrocer") {
8    # Access the opening hours (where specified)
9    hours {
10      # Use the forDays operation to obtain days across a range of dates. By
11      # default, without any arguments the next 7 days will be selected. You
12      # can change the range by specifying an alternative offset (which allows
13      # you to specify values like { days: 14 }) or provide a specific start and
14      # end dates (as ISO-8601 date strings)
15      forDays {
16        # Date/day, as ISO-8601, or as formatted for presentation using the
17        # Unicode Technical Standard #35 Date Field Symbols
18        date(format: "EEE, MMM d")
19        # Whether there is a public holiday for this date detected for this
20        # region on this date
21        publicHolidays
22        # Obtain the intervals for this date, requesting the opening status
23        # status is optional, otherwise use Open/Closed to specify your pref
24        intervals(status: Open) {
25          # Hours, from/to as ISO-8601 string, or formatted using the Unicode
26          # Technical Standard #35 Date Field Symbols
27          from(format: "h:mm a")
28          to(format: "h:mm a")
29          # Status (Open/Closed)
30          status
31          # Any corresponding comment for the opening hours
32          comment
33        }
34      }
35    }
36  }
37}

Sandbox: Configure | Try Operation

On a success, your response will look similar to the following:

1{
2  "data": {
3    "place": {
4      "hours": {
5        "forDays": [
6          {
7            "date": "Mon, Jan 23",
8            "publicHolidays": [],
9            "intervals": [
10              {
11                "from": "7:00 AM",
12                "to": "3:30 PM",
13                "status": "Open",
14                "comment": null
15              }
16            ]
17          },
18          {
19            "date": "Tue, Jan 24",
20            "publicHolidays": [],
21            "intervals": [
22              {
23                "from": "7:00 AM",
24                "to": "3:30 PM",
25                "status": "Open",
26                "comment": null
27              }
28            ]
29          },
30          {
31            "date": "Wed, Jan 25",
32            "publicHolidays": [],
33            "intervals": [
34              {
35                "from": "7:00 AM",
36                "to": "3:30 PM",
37                "status": "Open",
38                "comment": null
39              }
40            ]
41          },
42          {
43            "date": "Thu, Jan 26",
44            "publicHolidays": ["Australia Day"],
45            "intervals": [
46              {
47                "from": "7:00 AM",
48                "to": "3:30 PM",
49                "status": "Open",
50                "comment": null
51              }
52            ]
53          },
54          {
55            "date": "Fri, Jan 27",
56            "publicHolidays": [],
57            "intervals": [
58              {
59                "from": "7:00 AM",
60                "to": "3:30 PM",
61                "status": "Open",
62                "comment": null
63              }
64            ]
65          },
66          {
67            "date": "Sat, Jan 28",
68            "publicHolidays": [],
69            "intervals": [
70              {
71                "from": "8:00 AM",
72                "to": "3:30 PM",
73                "status": "Open",
74                "comment": null
75              }
76            ]
77          },
78          {
79            "date": "Sun, Jan 29",
80            "publicHolidays": [],
81            "intervals": [
82              {
83                "from": "9:00 AM",
84                "to": "3:30 PM",
85                "status": "Open",
86                "comment": null
87              }
88            ]
89          }
90        ]
91      }
92    }
93  }
94}

Upcoming Open/Closed hours using intervals() connection

The intervals() operation provides you the information about the immediate next open/closed hours for a place. You are provided back a series of from/to window intervals along with the associated status and comment.

This operation was designed to assist user interfaces that wish to present the next time a venue is open, or perform more nuanced interface messages, such as "opening soon" or "closing soon".

1# Query the next series of open/closed hours for a place, in order to present
2# information whether the venue is open, closed, opening soon, closing soon,
3# etc.
4
5query QueryUpcomingOpenClosedTimes {
6  # Use the place() operation
7  place(id: "place/facebook:page:mavisthegrocer") {
8    # Access the opening hours (where specified)
9    hours {
10      # Access the next window that the place is open. Supports selecting a
11      # series of Open/Closed hours and can be used to let users know when
12      # a venue will be open/closed next.
13      intervals(first: 2) {
14        # First node is the current state, second node is the upcoming change
15        # of status.
16        nodes {
17          # Times from/to as ISO-8601 string, or formatted using the Unicode
18          # Technical Standard #35 Date Field Symbols
19          from(format: "EEE, MMM d, h:mm a")
20          to(format: "EEE, MMM d, h:mm a")
21          # Create a relative expression (in X minutes/hours etc) based on a
22          # a supplied relative to ISO 8601, or null (for now)
23          relative: from(relativeTo: null)
24          # Status Open/Closed
25          status
26          # Any comments attached to the opening hours
27          comment
28          # Access any local public holidays that may affect these hours
29          publicHolidays {
30            name
31          }
32        }
33      }
34    }
35  }
36}

Sandbox: Configure | Try Operation

Checking a status at a future specific datetime

Note: You can also use the interval() method to check the opening hours at a specific date/time in the future. This can give you spot checks when assisting a user with checking a future travel date. You can also access whether there are any public holidays that could affect that time. Use a query providing the from field argument (with optional to value) in order to check the status at a point of time: interval(from:"<ISO8601_DATE>", first: 1) { status }.

OpenStreetMap Opening Hours Specification osmTag

Opening Hours can also be accessed as a string according to the OpenStreetMap (OSM) opening hours tag specification.

1Mo,Tu,Th,Fr 12:00-18:00; Sa,PH 12:00-17:00

Working with Date/Times

The fields of date/from/to return ISO-8601 strings with time zones. You can supply arguments to these fields to format the return string so that you can control the presentation.

Supply format to provide an output based on the Unicode Technical Standard TR35 - Date Field Symboles to return dates such as Wed, Mar 31 etc. These can make dates easier to include on the front-end.

You can optionally provide your own timeZone (such as Australia/Melbourne), to format the output of the date/times, relative to another time zone, such as a visitors local time zone.

You can also make use of a relativeTo field argument, supplying either null to take the current date/time, or a ISO-8601 string, and will provide a relative time expression (such as in 8 hours).

Finally, for internationalisation, you can also provide a locale in order to output strings in a preferred user language.

Time zone

Dates, including the from/to fields, are formatted in ISO-8601 standard and are based on UTC. This enables you to present the hours considerate of time zone differences of the user to the place. You can also access the time zone of places using the place/time-zone attribute.

Regions for identifying Public Holidays

Alpaca source a list of public holidays from publicly accessible and maintained sources. If you would like to access the public holiday information from an alternative source, it may be beneficial to use some of the other attributes to locate the place against other sources. For this purpose, Alpaca provides the ISO-3166-2 for the place, allowing you to access the country and region.

More Resources

• Example React Opening Hours