# OpenStreetMap opening hours editor

The OpenStreetMap opening hours specification is fairly complex and does not readily lend itself to a simple and intuitive user interface.

However most of the time you will likely only be using a small part of the definition. The editor takes this in to account by trying to hide the more obscure features in menus and most of the time reducing the "on the road" use to small customizations of pre-defined templates.

This documentation is preliminary and a work in progress

## Using the opening hours editor

In a typical workflow the object you are editing will either already have an opening hours tag (opening_hours, service_times and collection_times) or you can re-apply the preset for the object to get an empty opening hours field. If you need to add the field manually and you are using Vespucci you can enter the key on the details page and then switch back to the form based tab to edit. If you believe that the opening hours tag should have been part of the preset, please open an issue for your editor.

If you have defined a default template (do this via the "Manage templates" menu item) it will be loaded automatically when the editor is started with an empty value. With the "Load template" function you can load any saved template and with the "Save template" menu you can save the current value as a template. You can define separate templates and defaults for the "opening_hours", "collection_times" and "service_times" tags. Further you can limit applicability of a template to a region and a specific identifier, typically an OSM top-level tap (for example amenity=restaurant).

Naturally you can build an opening hours value from scratch, but we would recommend using one of the existing templates as a starting point.

If an existing opening hours value is loaded, an attempt is made to auto-correct it to conform to the opening hours specification. If that is not possible the rough location where the error occurred will be highlighted in the display of the raw OH value and you can try and correct it manually. Roughly a quarter of the OH values in the OpenStreetMap database have problems, but less than 10% can't be corrected, see OpeningHoursParser for more information on what deviations from the specification are tolerated.

### Main menu button

- Add rule: add a new rule.
- Add rule for holidays: add a new rule for a holiday together with a state change.
- Add rule for 24/7: add a rule for an object that is always open, the opening hours specification doesn't support any other sub values for 24/7 however we do allow adding of higher level selectors (for example year ranges).
- Load template: load an existing template.
- Save to template: save the current opening hours value as a template for future use.
- Manage templates: edit, for example change the name, and delete existing templates.
- Refresh: re-parse the opening hour value.
- Delete all: remove all rules.

### Rules

Default rules are added as normal rules, this implies that they will override the values of previous rules for the same days. This can be a concern when specifying extended times, typically you will then want to switch the rules via the Show rule type menu entry to additive.

#### Rule menu

- Add modifier/comment: change the effect of this rule and add an optional comment.
- Add holiday: add a selector for public or school holidays.
- Add time span...
  - Time - time: a start time to an end time on the same day.
  - Time - extended time: a start time to an end time on the next day (example 26:00 is 02:00 (am) the next day).
  - Var. time - time: from a start variable time (dawn, dusk, sunrise and sundown) to an end time on the same day.
  - Var. time - extended time: from a start variable time to an end time on the next day.
  - Time - var. time: a start time to an end variable time.
  - Var. time - var. time: a start variable time to an end variable time.
  - Time: a point in time.
  - Time-open end: from a start point in time onwards.
  - Variable time: at the variable time
  - Variable time-open end: from a start variable time onwards
- Add week day range: add a weekday based selector.
- Add date range...
  - Date - date: from a start date (year, month, day) to an end date.
  - Variable date - date: from a start variable date (currently the specification only defines easter) to an end date.
  - Date - variable date: from a start date to a variable date.
  - Variable date - variable date: from a start variable date to an end variable date.
  - Occurrence in month - occurrence in month: from a start weekday occurrence in a month to the same.
  - Occurrence in month - date: from a start weekday occurrence in a month to a end date.
  - Date - occurrence in month: from a start date to an end weekday occurrence in a month.
  - Occurrence in month - variable date: from a start weekday occurrence in a month to an end variable date.
  - Variable date - occurrence in month: from a start variable date to an end weekday occurrence in a month.
  - Date - open end: from a start date onwards.
  - Variable date - open end: from a start variable date onwards.
  - Occurrence in month - open end: from a start weekday occurrence in a month onwards.
  - With offsets...: the same entries as above however with offsets specified (this is rarely used).
- Add year range: add a year based selector.
- Add week range: add a week number based selector.
- Duplicate: create a copy of this rule and insert it after the current position.
- Show rule type: display and allow changing of the rule type normal, additive and fallback (not available on the first rule).
- Move up: move this rule up one position (not available on the first rule).
- Move down: move this rule down one position.
- Delete: delete this rule.

### Time spans

To make editing time spans as easy as possible, we try to choose an optimal time range and granularity for the range bars when loading existing values. For new time spans the bars start at 6:00 (am) and have 15 minute increments, this can be changed via the menu.

Clicking (not on the pins) the time bar will open the large time picker, when using the bars directly is too difficult. The time pickers extend in to the next day, so they are a simple way to extend a time range without having to delete and re-add the the range.

#### Time span menu

- Display time picker: show a large time picker for selecting start and end time, on very small displays this is the preferred way of changing times.
- Switch to 15 minute ticks: use 15 minute granularity for the range bar.
- Switch to 5 minute ticks: use 5 minute granularity for the range bar.
- Switch to 1 minute ticks: use 1 minute granularity for the range bar, very difficult to use on a phone.
- Start at midnight: start the range bar at midnight.
- Show interval: show the interval field for specifying an interval in minutes.
- Delete: delete this time span.

### Manage templates

The template management dialog allows you to add, edit and delete templates.

In Android 4.4 and later the following additional functionality is available from the menu button.

- Show all: display all templates in the database.
- Save to file: write the contents of the template database to a file.
- Load from file (replace): load templates from a file replacing the current contents of the database.
- Load from file: load templates from a file retaining the current contents.