Home / GIS and Open Map Data for Beginners

OpenStreetMap Opening Hours: The opening_hours Grammar, Decoded

An open sign with opening hours displayed on the glass door of a café

Photo: Valeriia Miller / Pexels

When OpenStreetMap says a cafe opens at nine, that fact is stored as a string like Mo-Fr 08:00-17:00, written in a notation most mappers copy from an example and few can actually read. The opening_hours syntax is a genuine little language, with a formal specification maintained alongside the OSM wiki's Key:opening_hours page, an evaluation library that parses it, and enough expressive power to encode seasonal schedules, holiday exceptions, and lunch breaks. It is also unforgiving: one wrong character makes a value unparseable, and an unparseable value helps nobody. This guide teaches the grammar properly, element by element, with worked decodings, so you can write values that parse, and read the values other mappers wrote.

Interactive tool

Write Hours That Parse: The Grammar Checklist

Check off each step as you finish it. Your progress stays on this page.

0 of 7 complete

0% done

The Building Blocks: Days, Times, and Ranges

Everything is built from three pieces. Weekdays are two-letter codes: Mo Tu We Th Fr Sa Su. Times are 24-hour, written 08:00. A time range joins two times with a hyphen: 08:00-17:00. A day range joins two day codes the same way: Mo-Fr. Put a day selector and a time range together and you have the language's basic sentence:

Mo-Fr 08:00-17:00 reads as: Monday through Friday, open from 8 in the morning to 5 in the afternoon. Outside those hours, and on Saturday and Sunday, the feature is understood to be closed; opening_hours describes when something is open, and silence means closed. That one pattern covers a large share of the world's shops, which is why most values you meet are this short. Everything else in the grammar exists for the places whose weeks are less tidy.

Multiple Intervals: The Comma

Many businesses open twice a day, closing over lunch. The comma separates additional time ranges within the same rule:

Mo-Fr 08:00-12:00,13:00-17:00 reads as: weekdays, open 8 to 12, closed for the midday hour, open again 1 to 5. Commas also separate day lists when the days are not a range: Mo,We,Fr 09:00-13:00 is a business open Monday, Wednesday, and Friday mornings. The comma always means "and also this," inside one rule, one statement about one set of days. Keep that meaning in mind, because the next separator means something stronger.

Rule Sets: The Semicolon, and Why Order Is Law

The semicolon separates rules, and rules are evaluated in order, with later rules overriding earlier ones where they conflict. This is the mechanism for exceptions:

Mo-Fr 08:00-17:00; Sa 09:00-13:00; Dec 25 off reads as: the general weekday rule; then a Saturday rule; then a specific closure. The most-used override word is off, which states closed for its selector: Su off appended to a week that would otherwise include Sunday closes it explicitly, and PH off closes the feature on public holidays. The override order is what makes the language manageable: write the general pattern first, then stack the exceptions after it, each semicolon narrowing what came before. A reader, human or machine, processes the string the way you would read a shop door: the printed hours, then the handwritten notes beneath, each note winning over the print where they disagree.

A café entrance with a chalkboard sign showing opening hours
A café entrance with a chalkboard sign showing opening hours

Months, Seasons, and Holidays: PH, SH, and the Calendar Selectors

Real schedules bend with the year, and the grammar has selectors for it. Months are three-letter codes, Jan through Dec, usable as ranges: Apr-Oct Mo-Su 09:00-19:00; Nov-Mar Mo-Su 10:00-16:00 is the classic seasonal pair, a business with summer hours and winter hours, each rule fenced to its months so neither leaks into the other's season. Weeks of the year can be selected too, for schedules tied to terms and seasons. The holiday codes are the ones mappers most often need and least often know: PH means public holidays, SH means school holidays, and each takes the treatment the rule gives it, most commonly PH off (closed on public holidays) or a PH rule with its own shorter hours. Because holiday calendars differ by country and region, the evaluation of PH depends on where the feature is, which the parsing tools know from context; the tag itself just says "holidays," honestly leaving whose holidays to geography.

Time Terms Beyond the Clock: Sunrise, Sunset, and 24/7

Some opening times are not clock times at all. The grammar accepts sunrise and sunset as time terms, with offsets in parentheses for the places that open a fixed interval after dawn or close before dark: a park tagged with a dawn-to-dusk rule follows the sun through the year without anyone editing the tag, because the evaluator computes the sun's times for the feature's location and date. And at the far end of simplicity sits 24/7, the complete value for features that never close: no days, no times, just the statement. It is the most valuable value in the whole system per character, and the one most often written wrong by mappers who spell out Mo-Su 00:00-24:00 instead; the short form is the correct one, and tools display it as "open now" at every hour of every day.

Worked Decodings: Reading Real Values

Fluency comes from reading, so decode three values end to end. Tu-Th 09:00-18:00; Fr 09:00-20:00; Sa 10:00-14:00; Su,PH off: a shop open Tuesday to Thursday nine to six, Friday until eight, Saturday ten to two, closed Sundays and public holidays; Monday is absent, therefore closed. Mo-Su sunrise-sunset; Dec 25 off: a place, typically a park or cemetery, open every day from dawn to dusk, except Christmas Day. Apr-Oct Mo-Sa 09:00-18:00; Nov-Mar Mo-Sa 10:00-16:00; PH off: a seasonal business, longer hours April through October, shorter hours November through March, closed on public holidays all year; note how the PH rule stands outside the month fences because it overrides in both seasons. If you can read those three aloud without hesitation, you can read nearly every value on the map.

Check Before You Save: The Evaluation Tool

The specification's companion is an evaluation tool (the opening_hours.js library and its public test page), where you paste a value and watch it parsed: rendered as a calendar, checked for syntax errors, and resolved against real dates including holidays and sun times. Use it the way programmers use a compiler: every non-trivial value goes through it before saving. It catches the five errors that make real-world values unparseable: spaces where the grammar wants none or the reverse, a 12-hour time written into a 24-hour language, a day code misspelled by one letter, a comma where a semicolon was meant (which silently merges two rules into nonsense instead of overriding), and a range written backwards. A value that fails to parse is worse than no value, because it looks like information. The two minutes in the evaluator are the difference between tagging the world's hours and decorating the database, and they are the cheapest quality step in all of OpenStreetMap editing, as our report errors guide would remind anyone who later has to flag the mistake.

Comments and States: The Words After the Rules

The grammar has a human margin. A rule may end with a comment in double quotes, free text the specification preserves for the situations numbers cannot carry: Mo-Fr 08:00-17:00 "or by appointment" tells the reader the rule and its exception in one value, and evaluation tools display the comment rather than choking on it. A rule may also carry an explicit state, open or closed, for the cases where a time range alone misleads (a facility staffed but not serving, a gate unlocked but the venue shut). Use both sparingly and honestly: comments are for the durable exception, not for narrative ("usually opens a bit late" is a review, not data), and a quoted comment never substitutes for a rule the grammar can express. The margin exists because the world's hours include a residue of human arrangements no formal language fully domesticates; the discipline is to keep the residue small, quoted, and at the end, where the parser and the reader both know to look for it.

Beyond Shops: The Same Grammar Everywhere

Nothing in the language is specific to retail, and the map applies it wherever things keep hours: libraries and government offices, pharmacies and clinics, public toilets and drinking fountains, charging stations and car parks, ticket offices and tourist information points, the gates of cemeteries and the desks of hotels. The grammar's selectors stretch accordingly: school holidays matter to a swimming pool's family hours, sunrise rules govern trailheads and boat ramps, seasonal month fences describe everything from ski lifts to beach concessions. Learning to write opening_hours once buys you the ability to describe the schedule of nearly anything a community runs on a timetable, and learning to read it buys you the stranger's skill of looking at any tagged place on the map and knowing, precisely, whether it will be open when you get there. That is a remarkable amount of power for a string of codes, and it is why this small language rewards the hour it takes to learn it properly.

The Door Test: Tagging From What Is Printed

The most reliable source for an opening_hours value is the sign on the door, and the grammar was designed by people who transcribe those signs. Photograph or note the sign exactly, including its exceptions line ("closed public holidays," "kitchen closes one hour before"), because the sign's own structure maps one-to-one onto the language: the main hours are the base rule, the exceptions line is the semicolon overrides, and the seasonal notice is a month-fenced second rule. Transcribe in the evaluator before saving, since the sign's casual punctuation ("8am to 5pm, Mon to Fri") must become the grammar's strict form, and the evaluator is where casual becomes strict without guessing. Where the sign and the business's website disagree, believe the sign: it is the one the business must honor at the door, and it is the one a visitor standing there will test your data against. The map's hours are only as good as its transcriptions of ten thousand doors; each careful one makes the next traveler's evening measurably less uncertain, which is a fine return on ninety seconds with a phone camera and a parser.

Related Guides

If this page answered part of the question, these GIS guides cover the rest of the same ground:

Frequently Asked Questions

What does Mo-Fr 08:00-17:00 mean?

Monday through Friday, open from 08:00 to 17:00. Weekdays use two-letter codes, times are 24-hour, and anything not covered by a rule is understood to be closed. It is the most common opening_hours pattern on the map.

How do I tag a lunch break or split hours?

With a comma inside the rule: Mo-Fr 08:00-12:00,13:00-17:00 means open 8 to 12, closed for an hour, open again 1 to 5. The comma adds another interval to the same days; a semicolon would start a new rule instead.

What do PH and SH mean in opening_hours?

PH means public holidays and SH means school holidays. They are used as selectors, most often in an override rule such as PH off, meaning closed on public holidays. Which holidays apply depends on the feature's country and region, resolved by the evaluating tool.

How do I tag something that is always open?

Use the value 24/7 on its own. Do not spell it out as Mo-Su 00:00-24:00; the short form is the correct, standard value, and tools recognize it as open at every hour.

How can I check an opening_hours value before saving it?

Paste it into the opening_hours evaluation tool, which parses the value, draws it as a calendar, resolves holidays and sunrise or sunset terms for a location and date, and reports syntax errors. Every non-trivial value deserves this check, because an unparseable value looks like information but functions as none.

Photo credits: Valeriia Miller (Pexels); Robert So (Pexels). Photos are served from this site; follow the credit to the library page for the original.