Timeshape

When calling TimeZoneEngine.initialize, you can pass a boolean parameter accelerateGeometry. If set to true, Timeshape builds a bitmap index for each polygon. This increases initialization time and memory usage but speeds up typical point-in-polygon queries by approximately 2.5 times.

// Example of enabling acceleration (parameter is the last argument in relevant overloads)
TimeZoneEngine engine = TimeZoneEngine.initialize(timeZones, true);

Timeshape converts GeoJSON source data containing time zones into a highly efficient format for storage and querying. It packages the converted data together with the querying code into a single JAR file.

Key technical details:

• Data Format: Uses compressed Protocol Buffers (protobuf) with ZStandard compression.
• Optimization: Uses float instead of double for geographic coordinates to reduce size (8 bytes per point instead of 16 bytes), which provides significant savings without sacrificing necessary precision.
• Indexing: At runtime, it builds a spatial index using a quad tree (via the Esri geometry API) to enable efficient querying.

Android developers must configure the app-level build.gradle to exclude the standard compression library and explicitly import the native component AAR for zstd-jni to ensure compatibility.

implementation('net.iakovlev:timeshape:2026b.29') {
  // Exclude standard compression library
  exclude group: 'com.github.luben', module: 'zstd-jni'
}
// Import aar for native component compilation
implementation 'com.github.luben:zstd-jni:1.5.7-11@aar'

If you have published a modified version of Timeshape locally using core/publishLocal or core/publishM2, you must configure your project's build definition to include the local repository.

### With sbt/scala
```scala
resolvers += Resolver.mavenLocal

With gradle/java

repositories {
    mavenCentral()
    mavenLocal()
}

dependencies {
    compile group: 'net.iakovlev', name: 'timeshape', version: '2023b.18-SNAPSHOT'
}

Add the following dependency to your pom.xml to use Timeshape in your Java project. Note that starting from release 2023b.20, the library supports Java 8.

<dependency>
    <groupId>net.iakovlev</groupId>
    <artifactId>timeshape</artifactId>
    <version>2026b.29</version>
</dependency>

The default memory footprint for loading the entire world's time zone data is approximately 128 MB. You can reduce this memory usage by limiting the geographic area of the time zones loaded. This is achieved by calling TimeZoneEngine.initialize with specific coordinate boundaries.

TimeZoneEngine.initialize(double minlat, double minlon, double maxlat, double maxlon);

To query a sequence of points (like a GPS trace), use engine.queryPolyline(double[] points). This method is significantly faster than calling query() individually for every point in the trace.

// points should be an array of coordinates
List<SameZoneSpan> spans = engine.queryPolyline(points);

Because some geographic points belong to multiple time zones, use engine.queryAll(double latitude, double longitude) to retrieve a List<ZoneId> containing all applicable zones. This is preferred over query() when you need to apply specific business logic to choose between overlapping zones.

import java.time.ZoneId;
import java.util.List;

List<ZoneId> allZones = engine.queryAll(52.52, 13.40);

Use engine.query(double latitude, double longitude) to find the ZoneId for a specific point. If the point belongs to multiple overlapping time zones, this method returns only one arbitrary ZoneId wrapped in an Optional.

import java.util.Optional;
import java.time.ZoneId;

Optional<ZoneId> maybeZoneId = engine.query(52.52, 13.40);

The getKnownZoneIds() method returns a List<ZoneId> containing all unique time zones currently indexed.

List<ZoneId> allZones = index.getKnownZoneIds();