New timezone library

I just finished a new library named particle-timezone. Yes, it’s another timezone library.

TzCfg from @Bear is a good solution, but I needed something that was more reliable than ip based location and something that’s scalable and reliable/self-hosted ( seems to be gone)
edit: is not gone! looks like my adblocker got a little overzealous.

particle-timezone comes with (the source of) a Google Cloud app engine flex server (timezone-server). Once you have your google cloud account up and running, it’s very easy to deploy.
The server gets the local WiFi info from the Particle device via a webhook and then hits the Google Maps geolocation API and the timezone API to figure out the local timezone and DST offset.

The library is very similar to the Particle Google Maps integration by @rickkas7 , but just hits one extra api for the timezone, and it comes with the actual server.


#include "timezone.h"

Timezone timezone;

void setup() { 

void loop() {
  if (Particle.connected() && !timezone.isValid())

The library can definitely use some more work, pull request are more than welcome!

Some features that would be welcome are:

  • storing timezone data in EEPROM like TzCfg does
  • automatic updating of timezone
  • automatic update of DST offset
  • add support for Boron and cell tower location like the Particle Google Maps integration
  • make the server a little more robust (more error checking, more logging, …)

Feedback appreciated and which features are still missing?


Hello Jelmer,

First, thanks for your efforts on a new library; in hours of searching for a solution to timezone and GPS, I found pages of difficult to implement solutions, but nothing that was concise enough for my needs. I spent a while trying to implement various solutions, but I think your new library probably can solve my problem; please see the below. Thanks for your time.

Hardware: Particle Boron and Adafruit Ultimate GPS
Desired Solution: display time in local vice UTC
Code: This is a simple snippet of what I’m using to retrieve the GPS DTG. I can include the entire file if needed. The below works well for retrieving the current GPS data and publishing it to Particle Console. My only issue with my data so far is the UTC vs local time. I was just subtracting 4 for EST, until it hit 2000 (EST) and 0000 UTC, and I ended up with negative times and fell down this rabbithole.

if (GPS.fix) {
    Particle.publish("DTG: ", "Date: " + String(GPS.month, DEC) + "/" + String(, DEC) + "/" + String(GPS.year, DEC) + " Time (UTC): " + String(GPS.hour, DEC) + ":" + String(GPS.minute, DEC) + ":" + String(GPS.seconds, DEC), 300, PRIVATE));
    Particle.publish("Location Data: ", "LAT/LONG: " + String(GPS.latitudeDegrees) + " " + String(GPS.longitudeDegrees) + " MPH: " + String(GPS.speed*1.151) + " Azimuth: " + String(GPS.angle) + " Altitude (feet): " + String(GPS.altitude/3.28084) + " Satellites: " + String((int)GPS.satellites), 300, PRIVATE);

Your GPS is only giving you UTC time, so you can sync UTC time with the Particle OS clock with the setTime() function. This way your timestamp will be more precies than when the clock is synced via the particle device cloud.

To figure out your local time and daylight savings time offset, you could use this library. It will just add the correct offsets, and when you print the time with Time.format(time, TIME_FORMAT_ISO8601_FULL); you should see the correct local time and offset.

But since your hardware has a GPS, so you have a very precise location available, and you’re logging it, it might be easier to handle all this server side, instead of on the Boron.
You can use the Google Maps Timezone API to figure out the correct timezones based on the GPS coordinates you’re getting from the device.

If you need the local time on the Boron itself for some reason, you could augment the library to send the local coordinates to the server (instead of the local WiFi AP mac addresses). The server then would need to do one API lookup less, since it already has the location of the device.
If you do add this functionality to the library, don’t forget to submit a pull request, this would be a cool feature to add to the library!

You could also run both systems parallel: GPS for time sync and WiFi AP mac addresses + this lib to figure out the timezone and DST offset. But that would be sub-optimal, since the GPS coordinates would be a better choice to figure out the local time zone.