GeoGarage Time Zone API

for maritime areas

Peio

What time is it here at sea ? About nautical time

A ship within the territorial waters of any nation uses that nation's time.

In international waters, time zone boundaries are meridians 15° apart, except that UTC−12 and UTC+12 are each 7.5° wide and are separated by the 180° meridian (not by the International Date Line, which is for land and territorial waters only).

A captain can change ship's clocks any time after entering a new time zone.

The solution : The GeoGarage maritime Time Zone API

The GeoGarage maritime Time Zone API provides a simple interface to request the time zone for a location on oceans and seas, as well as that location's time offset from UTC.

Effectively, the other APIs available on the market such as the Google Time Zone API only manages land/earth locations :

"Note that time zone data may not be available for locations over water, such as oceans or seas.”

source : https://developers.google.com/maps/documentation/timezone/

Our GeoGarage TZ database is updated periodically to reflect changes made by political bodies to time zone boundaries, UTC offsets and daylight-saving rules.

Introduction

Requesting the time zone information for a specific Latitude/Longitude pair whatever on the whole planet will return the name of that time zone, the time offset from UTC, and the Daylight Savings offset.

You access the GeoGarage Time Zone API through an HTTPS interface.

Audience

This document is intended for website and mobile developers who want to include time data on nautical maps provided by the GeoGarage nautical charts API. 

Note : today, the GeoGarage Time Zone API can't be sold independently to the usual nautical charts API.

Odoo image and text block

A Time Zone API specific for maritime areas

GeoGarage Time Zone worldwide map

The colors have been chosen to reflect the offset from GMT and the outlines show the boundaries and maritime territorial limits of the time zones of the world.

Time Zone Requests

The GeoGarage Time Zone API returns time zone data for a point on the oceans, specified by a Latitude/Longitude pair. 

A Google Time Zone API URL must be of the following form:

https://geogarage.com/api/timezone/xml?location=Lat,Lon&timestamp=time&key=API_KEY

Ex : https://geogarage.com/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331161200&key=API_KEY

  • location: a comma-separated lat,lng tuple (eg. location=39.6034810,-119.6822510, representing the location to look up.
  • timestamp specifies the desired 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. Times before 1970 can be expressed as negative values.
  • key — your application's API key. This key identifies your application and client number.

Important: Requests must be submitted via https, not http.

  

Output Formats

Outputs formats are specified using the trailing service flag in the request URL. The GeoGarage Time Zone API supports the following output formats:

  • /json returns results in JavaScript Object Notation (JSON).
  • /xml returns results in XML, wrapped within a <TimeZoneResponse> node.
The API returns the unix (Olson) Time Zone ID (e.g., "India/Andaman Is", "Europe/London"), the Windows Standard Name for the time zone (e.g., "Pacific Standard Time", "Central European Standard Time"), and the offset from UTC, either for the current time or for any date and time specified in thetimestamp parameter in the query string.