Timezone API
The Timezone API provides time offset data for locations on the surface of the earth.
Call the Timezone API in your application
This guide will help you seamlessly convert time across the globe!
Do You Have Your Access Token?
Before you proceed, ensure you have your access token at hand. Can't find your token? No worries — our guide will assist you in either creating a new one or finding your existing token.
1. Making Your First Timezone API Call
Assuming you have a set of coordinates at hand, such as latitude 48.8584 and longitude 2.2945, let's explore how to determine the timezone associated with these coordinates.
2. Request Timezone Information
Use the following URL to make the API call to the Timezone API:
https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=48.8584&lon=2.2945&format=json
Don't forget to replace YOUR_ACCESS_TOKEN with your token.
Sample Response:
If the API call is successful, you will receive a response in JSON format, resembling the following:
{
"timezone": {
"name": "Europe/Paris",
"now_in_dst": 1,
"offset_sec": 7200,
"short_name": "CEST",
"full_name": "Central European Summer Time"
}
}
The timezone value provides the timezone associated with the given coordinates.
3. Explore the Timezone API Reference for More
Refer to the Timezone API Reference for detailed information on tweaking responses, handling different formats, and applying additional configurations.
Tips & Best Practices
- Always use the API to get the most up-to-date timezone information, as daylight saving time rules can change.
- Include the specific timestamp in API calls for accurate results, especially for future dates or near DST transitions.
- Choose the endpoint (us1 or eu1) closer to the majority of your user base for optimal response times.
- Be mindful of API rate limits. Consider caching results to reduce redundant calls and retry failed requests after a short while
Brief Overview of Request / Response Parameters
The information presented below is a condensed summary. For a more detailed and exhaustive list of parameters, refer to API Reference Page.
Request
Requests can be sent to any of the following endpoints
Region 1: US
https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE×tamp=TIMESTAMP
Region 2: Europe
https://eu1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE×tamp=TIMESTAMP
Request Example
<?php
$curl = curl_init('https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE×tamp=TIMESTAMP');
curl_setopt_array($curl, array(
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_CUSTOMREQUEST => 'GET',
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo 'cURL Error #:' . $err;
} else {
echo $response;
}
import requests
url = "https://us1.locationiq.com/v1/timezone"
data = {
'key': 'YOUR_ACCESS_TOKEN',
'lat': 'LATITUDE',
'lon': 'LONGITUDE',
'timestamp': 'TIMESTAMP'
}
response = requests.get(url, params=data)
print(response.text)
var settings = {
"async": true,
"crossDomain": true,
"url": "https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE×tamp=TIMESTAMP",
"method": "GET"
}
$.ajax(settings).done(function (response) {
console.log(response);
});
curl --request GET \
--url 'https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE×tamp=TIMESTAMP'
Request Parameters
Name | Description | Required | Example |
---|---|---|---|
key | Authentication key | Yes | pk.867fac38d |
lat | Latitude of the location | Yes | 48.5748229 |
lon | Longitude of the location | Yes | 13.4609744 |
timestamp | Unix epoch time in seconds (number of seconds since January 1, 1970, 00:00:00 UTC). Defaults to current time if omitted. This parameter allows retrieval of time zone information for specific moments, which is useful for handling Daylight Saving Time changes and ensuring correct time zone offsets for historical data or future event scheduling. | No | 1792958398 |
Response
Response Example
{
"timezone": {
"name": "America/New_York",
"now_in_dst": 1,
"offset_sec": -14400,
"short_name": "EDT",
"full_name": "Eastern Daylight Time"
}
}
Response Parameters
Name | Description |
---|---|
timezone | Timezone object found for the location. |
Timezone object
Name | Description |
---|---|
name | Timezone identifier, compatible with the IANA Tz Database. Typically in the format "Area/Location" (e.g., "America/New_York", "Europe/Paris"), but can also include ocean areas (e.g., "Atlantic/Azores") and special administrative zones (e.g., "Etc/UTC", "Etc/GMT-14"). We always return the most current identifier (e.g., "Asia/Kolkata", not "Asia/Calcutta"). Note that "Etc/GMT" zones use POSIX-style signs, opposite to ISO 8601 convention (e.g., "Etc/GMT-14" is 14 hours ahead of GMT). |
now_in_dst | Represents whether the zone currently observing DST or not. |
offset_sec | The offset from UTC (in seconds) for the given location. Considers DST savings. |
short_name | Time zone abbreviation, usually 3 or 4 letters (e.g., "EDT" for Eastern Daylight Time, "CEST" for Central European Summer Time). In some cases, especially for locations without standardized abbreviations, it may be a numeric UTC offset (e.g., "+03" or "+0330"). |
full_name | Complete, descriptive name of the time zone, e.g. "Pacific Daylight Time" or "Central European Standard Time". For some locations (e.g., oceans) where such a name is unavailable, it is returned in the format of GMT±HH:MM (e.g., GMT+03:30). |
List of all response parameters available on the API Reference page
Example
Time Coordination with Timezone API: London and San Francisco
Here's a step-by-step guide that shows how to calculate the corresponding local time for a meeting in the United Kingdom at 10 am on June 14, 2024, for San Francisco.
1. Establish the Base Time
- Meeting time: June 14, 2024, 10:00 AM London time (BST)
- Unix timestamp: 1718355600
This timestamp corresponds to 10:00 AM British Summer Time (BST) on June 14, 2024.
2. Get Timezone Offset for London
Use LocationIQ's timezone API to get the timezone offset for London:
- London: (51.5074, -0.1278)
https://eu1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=51.5074&lon=-0.1278×tamp=1718355600
API Output for London:
{
"timezone": {
"name": "Europe/London",
"now_in_dst": 1,
"offset_sec": 3600,
"short_name": "BST",
"full_name": "British Summer Time"
}
}
This confirms that London is observing British Summer Time (BST), which is UTC+1.
3. Get Timezone Offset for San Francisco
Now, let's get the timezone information for San Francisco:
- San Francisco: (37.774929, -122.419416)
https://eu1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=37.774929&lon=-122.419416×tamp=1718355600
API Output for San Francisco:
{
"timezone": {
"name": "America/Los_Angeles",
"now_in_dst": 1,
"offset_sec": -25200,
"short_name": "PDT",
"full_name": "Pacific Daylight Time"
}
}
4. Calculate Local Times
- Base time (London): 10:00 AM BST
- Convert London time to UTC: 10:00 AM BST - 1 hour = 09:00 AM UTC
- San Francisco time: 09:00 AM UTC - 7 hours = 2:00 AM PDT
So, the meeting times are:
- London: 10:00 AM BST on June 14, 2024
- San Francisco: 2:00 AM PDT on June 14, 2024
Our San Francisco colleagues might need an extra strong coffee for this one.
Updated 3 months ago