Local Time API - Developers Guide

Quick Index

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:30 indicates that the given place is currently 3 hours and 30 minutes ahead of GMT/UTC time. A value of -4:45 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. This will ensure that you can receive timezone responses successfully.

Checking how many API credits you have remaining

You can check how many credits you have remaining at any time at the following URL: 

http://worldtimeengine.com/api/check/<apikey>
where apikey is your unique api key.

If the API Key that you used to check your credits is used, you will receive a key response, like: 

<key xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://worldtimeengine.com/key.xsd">
  <version>
    1.1
  </version>
  <requests>
    49967
  </requests>
  <expires>
    2011-10-13 23:59:59
  </expires>
</key>

Further Assistance

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