API Documentation

Quick Index

Sending a Request to the Local Time API

Local Time is delivered in JSON Format in response to a standard HTTP GET request.

To access the service, you will need to sign-up for one of our plans with our 3rd-party API hosting partner, Mashape Inc.

Once you have your key you will be able to send requests to the following URL:

https://worldtimeiodeveloper.p.mashape.com/geo?latitude=<latitude>&longitude=<longitude>
where <latitude> and <longitude> should be replaced with the latitude and longitude of the place to query.

Here's an example for Windhoek, Namibia:

https://worldtimeiodeveloper.p.mashape.com/geo?latitude=-22.5749&longitude=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 the WorldTime.io service. 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:

{
  "version": "1.2",
  "url": "http://worldtime.io/current/Wy0yMi41NzQ5LCAxNy4wODA1XXwxNy4wODA1fC0yMi41NzQ5",
  "location": {
    "region": "Namibia",
    "latitude": -22.5749,
    "longitude": 17.0805
  },
  "summary": {
    "utc": "2013-09-12 21:01:58",
    "local": "2013-09-12 23:01:58",
    "hasDst": true
  },
  "current": {
    "abbreviation": "WAST",
    "description": "West Africa Summer Time",
    "utcOffset": "+2:00",
    "isDst": true,
    "effectiveUntil": "2014-04-06 02:00:00"
  },
  "next": {
    "abbreviation": "WAT",
    "description": "West Africa Time",
    "utcOffset": "+1:00",
    "isDst": false,
    "effectiveUntil": "2014-09-07 02:00:00"
  }
}

The values returned in this type of response are detailed below:
  • version
    The version of the API currently being used. By default this will be 1.2.
  • url
    A web address pointing to the WorldTime.io website where the developer and/or user can view more information for the given coordinates.
  • 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.
  • hasDst
    Indicates whether the given place observes Daylight Saving Time (DST). A value of true indicates that the given place operates a Daylight Saving Time schedule.A value of false indicates that the given place does not use Daylight Saving Time.
  • 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 abbreviation 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 Saving 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:

{
  "code": 10001,
  "message": "Invalid or Expired API Key used"
}

The values returned in this type of response are detailed below:
  • 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, your usage history and other information related to your account via your developer dashboard at http://www.mashape.com.

Further Assistance

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