Skip to content
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Build Status


This is a very simplistic parser for string values according to the OSM opening hours specification. It is used in a number of OpenStreetMap projects, for example in Vespucci. As the opening hours specification is currently reasonably stable you shouldn't expect lots of activity in this repository.

It parses 147'002 (91%) of 161'268 unique test strings in non-strict mode. The remaining 14'266 are likely valid errors, spot checking shows that they have obvious issues. In strict mode further 15'807 fail (total 30'073).

Deviations from the grammar as of this version of the opening hours specification in all modes:

  • case-insensitive
  • leading 0s in times optional
  • unicode EN DASH (U+2013) EM DASH (U+2014) characters are allowed for hyphen
  • various unicode whitespace characters are ignored

In non-strict mode the following further differences are allowed:

  • three-character weekday abbreviations
  • German two-letter weekday abbreviations
  • times extending in to the next day that are missing the extra 24 hours are corrected
  • single 0 for minutes
  • minutes in times optional
  • ignore spaces and more than one leading zeros in minutes
  • "." and "h" as minutes separators
  • AM and PM time specifications are allowed (plus A.M. and P.M.)
  • holidays in weekday range
  • superfluous ":" after weekday range
  • 24/7 rules with preceding selectors are corrected to 00:00-24:00 time spans
  • list of month days after months ( Jan 1,4,5 )
  • " to " in lieu of a hyphen for ranges
  • date ranges that do not have the month day specified are corrected (Jan - Feb 15 -> Jan 1 - Feb 15)

Converting the data structures generated by parsing back to strings will result in correct data according to the specification.


try {
	OpeningHoursParser parser = new OpeningHoursParser(
		new ByteArrayInputStream(line.getBytes()));
	List<Rule> rules = parser.rules(strict);
	// ...
} catch(OpeningHoursParseException e) {
	// ...
	// e.getExceptions() will return a List<OpeningHoursParseException> 
	// containing more than one Exception if more than one issue was found 

Detailed documentation can be found in the JavaDoc.

Including in your project

We publish releases to Bintray/JCenter. The following snippets for build.gradle will make OpeningHoursParser available in your Gradle project:

repositories {
dependencies {
    compile "ch.poole:OpeningHoursParser:0.23.0"


Besides some unit tests, we run the parser on ~160'000 and compare with previous output to detect any changes in behaviour. If you are running these on windows, you may need to add org.gradle.jvmargs=-Dfile.encoding=UTF-8 to your to force correct use of the UTF-8 encoded test input.


The project uses gradle for building. Standard gradle tasks for the java plugin can be found here They can be invoked on the command line by running gradlew or gradlew.bat with the name of the task, for example gradlew jar to create the jar archive.

Note: the project has no runtime dependencies, and the jar file resulting from the build process is self-sufficient.


Pull requests are welcome.

As this library is used in a number of Android projects please restrict the use of Java 8 features and APIs to the Android supported subset see Check that any APIs used are supported on all Android platform API versions 10 and later, this is mainly an issue for APIs that were introduced with Java 7. This restriction will likely be relaxed for future versions.

Currently, the library is self-contained and doesn't have any runtime dependencies outside of basic Java support, it would be nice if we can keep it like that.


The error messages produced by the library are translated on transifex, see


Parser for string values according to the OSM opening hours specification





No packages published


You can’t perform that action at this time.