Timezone
Look up time offset data for any location on the surface of the earth, including DST handling.
The Unwired Labs TimeZone API provides time offset data for locations on the surface of the earth.
This API will be deprecated on 1st April 2027. Please migrate to the LocationIQ Timezone API - also an Unwired Labs product, and a more robust offering.
Usage
GET requests can be sent to the following URL:
https://us1.unwiredlabs.com/v2/timezone?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE
Replace us1 with a region that's closer to your location.
curl --request GET \
--url 'https://us1.unwiredlabs.com/v2/timezone?token=YOUR_API_TOKEN&lat=LATITUDE&lon=LONGITUDE'Query Parameters
| Name | Description | Required |
|---|---|---|
| token | Authentication token | Yes |
| lat | Latitude of the location | Yes |
| lon | Longitude of the location | Yes |
Response
The above command returns JSON structured like this:
{
"status": "ok",
"balance": 5000,
"timezone": {
"name": "Asia/Kolkata",
"now_in_dst": 0,
"offset_sec": 19800,
"short_name": "IST"
}
}| Name | Description |
|---|---|
| status | ok on success; error on error |
| balance | Balance left in the account |
| timezone | Timezone object found for the location. Read more |
Timezone Response
| Name | Description |
|---|---|
| short_name | Short name of the Timezone |
| offset_sec | The offset from UTC (in seconds) for the given location. Considers DST savings. |
| now_in_dst | Represents whether the zone currently observing DST or not |
| name | Timezone name of the Location |
Errors
Unlike our other APIs, this endpoint can respond with a non-200 HTTP status code, noted per error below - always check the status field in the response body in addition to the HTTP status code.
{
"status": "error",
"message": "Error message"
}When certain types of errors are encountered, the API responds with the following error messages:
| Error Message | HTTP Status | Description |
|---|---|---|
INVALID_TOKEN | 200 | The user's token set is not valid |
INACTIVE_TOKEN | 200 | The user's token is not active |
ACCESS_RESTRICTED | 403 | The access token does not have the geocoding:timezone scope required by this endpoint. |
INVALID_INPUT | 400 | The request does not contain the required input in the specified format |
NO_RESULTS | 200 | The request is valid and we could not find a timezone for the given coordinates |
DAILY_LIMIT | 429 | The daily quota for timezone lookups has been reached |
UNKNOWN_ERROR | 500 or 503 | Due to a server error, we are unable to serve your request. You can retry this request. |