Using the Time Zones API

Let’s get started with the API. The API has one option, the reverse look-up where the input is a set of GPS coordinates which are then translated to information regarding the time zone that these inputted coordinates are within. We will take you through some of the functionalities of the API step by step. If your questions aren’t answered on this site, please contact us.

In our examples, we will use Curl.

If you’re on Linux or OS X, you already have it installed. Windows users can get it here.
You can simply copy and paste the examples, but you will need to replace certain values with information that applies to your specific situation.

Getting started

GET YOUR FREE API KEY

First of all, you need to get some credentials. With an API key you will be able to access the related API and if applicable your usage will be automatically tracked and billed. Just click on the “GET YOUR FREE API KEY” button above, to apply for a free trial. Your API key will be between 30 and 128 characters long.

 

 

Getting time zone information

The XY2TZData API requires latitude and longitude coordinates as starting parameters.

xy2tzdata

Specify latitude (y) and longitude (x) values, as input parameters, for the location for which you wish to obtain time zone information in GeoJSON format. Furthermore, information about the local area in which the provided coordinates are located, is returned as well.

curl -X GET
  https://api.and.com/timezonesv1/xy2tzdata?x={longitude}&y={latitude}
  -H 'accept: application/json'
  -H 'x-api-key: {token}'
  -H 'cache-control: no-cache'
  -H 'content-type: application/json'

As mentioned, the result will contain info regarding the time zone and the local area, and therefore will have 2 parts, the “time_zone” and the “local_area“.

The “time_zone” part contains info regarding the time zone that was found:- category_code: time zone category code: 911

category_name: “time_zone”

time_zone: time zone in UTC format

country_ISO3_codes: ISO3 codes of the countries that fall (partially or totally) within the time zone.

local_boundary_names: names of the local boundaries that are contained within the time zone. These local boundaries can be related to a country but can also possibly be related to lower level administrations.

time_zone_abbreviations_names: array of arrays representing a list of pairs, where the first element of each pair is an abbreviation and the second element is a name. Each pair is a naming convention that is used for the time zone.

dst_time_zone_abbreviations_names: array of arrays representing a list of pairs, where the first element of each pair is an abbreviation and the second element is a name. Each pair is a naming convention that is used for the time zone when DST is active in a given boundary that is part of the time zone.

 

The “local_area” part contains info regarding the local area that was found:

local_boundary_id: id of the local area boundary found

country_ISO3_code: ISO3 of the country to which the local area belongs to

local_boundary_name: name of the local area.

time_zone: time zone in UTC format.

time_zone_local_abbreviation: local abbreviation used for the time zone to which this area belongs to.

time_zone_local_name: local name used for the time zone to which this area belongs to.

has_daylight_saving_time: true if the local area has a DST

dst_time_zone_local_abbreviation: local abbreviation used for the DST time zone to which this area belongs to.

dst_time_zone_local_name: local name used for the DST time zone to which this area belongs to.

dst_start: start of the DST period

dst_end: end of the DST period

 

The result will be:

{
  "time_zone" : {
    "category_name" : "time_zone",
    "category_code" : 0,
    "time_zone_abbreviations_names" : [ [ "time_zone_abbreviations_names", "time_zone_abbreviations_names" ], [ "time_zone_abbreviations_names", "time_zone_abbreviations_names" ] ],
    "local_boundary_names" : [ "local_boundary_names", "local_boundary_names" ],
    "dst_time_zone_abbreviations_names" : [ [ "dst_time_zone_abbreviations_names", "dst_time_zone_abbreviations_names" ], [ "dst_time_zone_abbreviations_names", "dst_time_zone_abbreviations_names" ] ],
    "time_zone" : "time_zone",
    "country_ISO3_codes" : [ "country_ISO3_codes", "country_ISO3_codes" ]
  },
  "local_area" : {
    "has_daylight_saving_time" : true,
    "dst_time_zone_local_name" : "dst_time_zone_local_name",
    "time_zone_local_abbreviation" : "time_zone_local_abbreviation",
    "dst_time_zone_local_abbreviation" : "dst_time_zone_local_abbreviation",
    "dst_start" : "dst_start",
    "time_zone_local_name" : "time_zone_local_name",
    "local_boundary_name" : "local_boundary_name",
    "dst_end" : "dst_end",
    "local_boundary_id" : 6,
    "time_zone" : "time_zone",
    "country_ISO3_code" : "country_ISO3_code"
  }
}

If the API token is incorrect you will receive {“message”:”Forbidden”}