Using Google Time Zone API to Convert DateTime between Geographic Locations in C#

It is extremely important that any application where the users are from different geographic locations handle date and time in a meaningful way. For an example, let’s say the application has users ranging from United States to Australia and right now, a user from Sydney, Australia creates a record in the database. So through out the application if we have only considered Sydney time, the created time for that particular record will be in Sydney time. If a user from Seattle, United States sees that record created time, it definitely is confusing because that time has not yet arrived to Seattle.

So in a world wide application, it is important to consider users’ time zones when maintaining date and times. There are variety of SDK for this such as Noda Time. But in this post, let’s see how we can consider not the time zones, but the geographic locations when converting the date time. For that we can use Google Time Zone API to convert date and time between geographic locations considering locations’ geographic coordinates.

Please note that to use Google Time Zone API, you will need to have a API key which can be acquired for free. Free API will have some request limitations, but it is more than enough to evaluate the functionality. In here, I am not going to explain how you can obtain the API key, please read this post to know how you can do it.

After getting the API key, next is to use it. Google Time Zone API expects following parameters.

• Timestamp
  • Timestamp specifies the given time as seconds since midnight, January 1, 1970 UTC. The Time Zone API uses the timestamp to determine whether or not Daylight Savings should be applied.
• Location's geographic coordinates
• API Key
• Language (optional)

If the request to Google TimeZone API gets succeeded, it will return a result containing details such as the offset for daylight-savings time in seconds (dstOffset), the offset from UTC in seconds for the given location(rawOffset),  time zone name etc. The converted time of a given location is the sum of the timestamp parameter,  dstOffset and rawOffset. Since it is again a Timestamp, we need to convert it back to DateTime value.

I am creating a console application and I am creating a class named “GoogleTimeZone”. There I have couple of local variables.

public class GoogleTimeZone

{

    private string apiKey;

    private GeoLocation location;

    private string previousAddress = string.Empty;

    public GoogleTimeZone(string apiKey)

    {

        this.apiKey = apiKey;

    }

}

Now let's create following helper methods.

First method is a method to return the Timestamp of a given DateTime.

private long GetUnixTimeStampFromDateTime(DateTime dt)

{

    DateTime epochDate = new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc);

    TimeSpan ts = dt - epochDate;

    return (int)ts.TotalSeconds;

}

Then the following method will do the opposite which is converting of Timestamp to DateTime.

private DateTime GetDateTimeFromUnixTimeStamp(double unixTimeStamp)

{

    DateTime dt = new DateTime(1970, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc);

    dt = dt.AddSeconds(unixTimeStamp);

    return dt;

}

Now the following method will return the coordinates for a given location. We can get the geographic coordinates by calling the Google Geocoding API.

private GeoLocation GetCoordinatesByLocationName(string address)

{

    string requestUri = string.Format("https://maps.googleapis.com/maps/api/geocode/xml?address={0}&key={1}", Uri.EscapeDataString(address), this.apiKey); 

    XDocument xdoc = GetXmlResponse(requestUri); 

    XElement status = xdoc.Element("GeocodeResponse").Element("status");

    XElement result = xdoc.Element("GeocodeResponse").Element("result");

    XElement locationElement = result.Element("geometry").Element("location");

    XElement lat = locationElement.Element("lat");

    XElement lng = locationElement.Element("lng");

    return new GeoLocation()

    {

        Latitude = Convert.ToDouble(lat.Value),

        Longitude = Convert.ToDouble(lng.Value)

    };

}

I have the following helper class to hold coordinates.

class GeoLocation

{

    public double Latitude { get; set; }

    public double Longitude { get; set; }

}

We now have the location and the time stamp. Following method will call the Google Time Zone API and get the converted time zone result.

private GoogleTimeZoneResult GetConvertedDateTimeBasedOnAddress(GeoLocation location, long timestamp)

{

    string requestUri = string.Format("https://maps.googleapis.com/maps/api/timezone/xml?location={0},{1}&timestamp={2}&key={3}", location.Latitude, location.Longitude, timestamp, this.apiKey); 

    XDocument xdoc = GetXmlResponse(requestUri); 

    XElement result = xdoc.Element("TimeZoneResponse");

    XElement rawOffset = result.Element("raw_offset");

    XElement dstOfset = result.Element("dst_offset");

    XElement timeZoneId = result.Element("time_zone_id");

    XElement timeZoneName = result.Element("time_zone_name"); 

    return new GoogleTimeZoneResult()

    {

        DateTime = GetDateTimeFromUnixTimeStamp(Convert.ToDouble(timestamp) + Convert.ToDouble(rawOffset.Value) + Convert.ToDouble(dstOfset.Value)),

        TimeZoneId = timeZoneId.Value,

        TimeZoneName = timeZoneName.Value

    };

}

I am grouping up the result to a class named GoogleTimeZoneResult as follows.

public class GoogleTimeZoneResult

{

    public DateTime DateTime { get; set; }

    public string TimeZoneId { get; set; }

    public string TimeZoneName { get; set; }

}

Finally I have the following public method which will trigger all the above methods.

public GoogleTimeZoneResult GetConvertedDateTimeBasedOnAddress(string address, DateTime dateTime)

{

    long timestamp = GetUnixTimeStampFromDateTime(TimeZoneInfo.ConvertTimeToUtc(dateTime));

    if (previousAddress != address)

    {

        this.location = GetCoordinatesByLocationName(address);

        previousAddress = address;

        if (this.location == null)

        {

            return null;

        }

    } 

    return GetConvertedDateTimeBasedOnAddress(this.location, timestamp);

}

That’s it. now let’s test the functionality using some test DateTime and calling the above public method from the Main.

static void Main(string[] args)

{

    GoogleTimeZone googleTimeZone = new GoogleTimeZone("your api key"); 

    string timeString = "2015-01-01T08:00:00.000+05:30";

    DateTime dt = DateTime.Parse(timeString);

    //string location = "Colombo, Sri Lanka";

    //string location = "Sydney, Australia";

    string location = "Seattle, United States";

    GoogleTimeZoneResult googleTimeZoneResult = googleTimeZone.GetConvertedDateTimeBasedOnAddress(location, dt);

    Console.WriteLine("DateTime on the server : " + dt);

    Console.WriteLine("Server time in particular to : " + location);

    Console.WriteLine("TimeZone Id : " + googleTimeZoneResult.TimeZoneId);

    Console.WriteLine("TimeZone Name : " + googleTimeZoneResult.TimeZoneName);

    Console.WriteLine("Converted DateTime : " + googleTimeZoneResult.DateTime);

}

Colombo, Sri Lanka

Colombo, Sri Lanka

Sydney, Australia

Sydney, Australia

Seattle, United States

Seattle, United States

I am uploading the sample code to OneDrive.

Happy Coding.

Regards,

Jaliya