Guide to using the World Time Engine Local Time API™

Quick Index

Sending a Request to the Local Time API
Receiving a Response from the Local Time API
Further Assistance

Sending a Request to the Local Time API

Local Time is delivered in Extensible Markup Language (XML) Format in response to a standard HTTP GET request.

To access the service, you will need to order an API key. Once you have your key you will be able to send requests to the following URL:

http://worldtimeengine.com/api/<apikey>/<latitude>/<longitude>

where apikey is your unique api key, and where latitude and longitude should be replaced with the latitude and longitude of the place to query.

Here's an example for Windhoek, Namibia:

http://worldtimeengine.com/api/9d89405104e16732fa00caa1e8e6cdfd/-22.5749/17.0805

Receiving a Response from the Local Time API

On sending a request as per the instructions above, you will receive a response from WorldTimeEngine.com. Depending on the validity of the API Key used in the request you will either receive a timezone response or an error response.

TIMEZONE: API Key Valid

If the API Key that you used to send your request validates successfully on the server, you will receive a timezone response, like:

<?xml version="1.0" encoding="UTF-8" ?>
<timezone xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="http://worldtimeengine.com/timezone.xsd">
    <version>1.1</version>
    <location>
        <region>Namibia</region>
        <latitude>-22.5749</latitude>
        <longitude>17.0805</longitude>
    </location>
    <time>
        <utc>2008-02-16 08:31:01</utc>
        <local>2008-02-16 10:31:01</local>
        <zone>
            <hasDST>true</hasDST>
            <current>
                <abbreviation>WAST</abbreviation>
                <description>West Africa Summer Time</description>
                <utcoffset>+2:00</utcoffset>
                <isdst>true</isdst>
                <effectiveUntil>2008-04-05 18:00:00</effectiveUntil>
            </current>
            <next>
                <abbreviation>WAT</abbreviation>
                <description>West Africa Time</description>
                <utcoffset>+1:00</utcoffset>
                <isdst>false</isdst>
                <effectiveUntil>2008-09-06 18:00:00</effectiveUntil>
            </next>
        </zone>
    </time>
</timezone>

The values returned in this type of response are detailed below:

location
Placeholder for the input that was used in the time lookup query.
latitude
The latitude that was passed to the API from the user. If the latitude is not a valid number, or the values entered exceed the acceptable coordinate ranges (-90<range<90) then this parameter is set to zero.
longitude
The longitude that was passed to the API from the user. If the longitude is not a valid number, or the values entered exceed the acceptable coordinate ranges (-180<range<180) then this parameter is set to zero.
time
Placeholder for the result of the time lookup query response.
utc
UTC time at which the query was executed on the server. ISO8601 formatted.
local
Local time, in relation to the utc query time (see above) for the given place. ISO8601 formatted.
zone
Placeholder for time zone date relating to the result of the time lookup query response.
abbreviation
Abbreviation of the timezone for the given place.
description
Description of the timezone for the given place. This field is used to elaborate on the meaning of the timezone abbreviation that is also returned (see abbr above).
utcoffset
Current time offset from UTC/GMT of the given place. For example, a value of 3.5 indicates that the given place is currently 3 hours and 30 minutes ahead of GMT/UTC time. A value of -4.75 would indicate that the given place is currently 4 hours and 45 minutes behind GMT/UTC time.
isdst
Indicates whether the given place is currently observing Daylight Savings Time (DST). A value of true indicates that the given place is currently observing DST. A value of false indicates that the given place is not currently observing DST OR that DST rules are not in use in this location.
effectiveUntil
The date and time (ISO8601 format) until the next timezone update occurs

ERROR: API Key Invalid or Expired

If the API Key that you used to send your request does not validate successfully on the server, you will receive an error response, like:

<?xml version="1.0" encoding="UTF-8" ?>
<error xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:noNamespaceSchemaLocation="http://worldtimeengine.com/error.xsd" type="exception">
    <code>10001</code>
    <message>Invalid or Expired API Key used</message>
</error>

The values returned in this type of response are detailed below:

type
The type of error that has been generated. This will be either exception, if a processing error occured, or server in the case of a system malfunction.
code
The error code of the error generated. Currently, we will only receive a 10001 error code, indicating that the API key used for the request is invalid or expired.
message
The error message returned by the system explaining the cause of the error generated.

In the case of an error response, you should check that the API key you are using is identical to the one provided when you signed up to the service and that this API key is still valid (12-months since the start of your subscription). This will ensure that you can receive timezone responses successfully.

Further Assistance

If you require further support or assistance please contact us and we will be happy to help.