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

For a hands-on experience, click here to make the API call right from your browser. 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": 0,
    "offset_sec": 3600,
    "short_name": "CET"
  }
}

The timezone value provides the timezone associated with the given coordinates.

3. Implement Timezone Information in Your Application

Utilize the obtained timezone information to enhance your application. Whether it's displaying local time or managing time-related features, these coordinates can now provide timezone context.

4. 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

• Endpoint Selection: Choose the endpoint (us1 or eu1) closer to the majority of your user base for optimal response times.
• URL Encoding: Ensure proper URL encoding, especially for address strings containing special characters or spaces.
• Rate Limits: Be mindful of API rate limits. Consider caching results to reduce redundant calls and retry failed requests after a short while.
• Handling Multiple Results: The API may return multiple results for ambiguous queries. Ensure your application can appropriately handle and display multiple timezone results.

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&timestamp=TIMESTAMP

Region 2: Europe

https://eu1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE&timestamp=TIMESTAMP

Request Example

<?php

$curl = curl_init('https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=LATITUDE&lon=LONGITUDE&timestamp=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&timestamp=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&timestamp=TIMESTAMP'

Request Parameters

timestamp parameter:

The timestamp parameter is used to specify a particular point in time for which you want to retrieve time zone information. It allows you to convert a specific timestamp to the corresponding time zone information, including the time offset from UTC and the time zone name.

Benefits:

• Accurate Time Zone Information: Supplying a timestamp enables precise time zone details, valuable for historical data and future event scheduling.
• Handling Daylight Saving Time Changes: The timestamp parameter ensures accurate management of Daylight Saving Time (DST) changes by accounting for varying time zone offsets.
• Event Scheduling: For scheduling events, the timestamp parameter is essential in determining the correct time zone for a specific event time.

Response

Response Example

{
  "timezone": {
    "name": "Asia/Kolkata",
    "now_in_dst": 0,
    "offset_sec": 19800,
    "short_name": "IST"
  }
}

Response Parameters

Timezone object

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 United Kingdom at 11 am on June 14, 2024, for San Francisco.

1. Get GMT Unix epoch time for meeting

The Unix Epoch time for 11am GMT on June 14, 2024 is 1718362800000

2. Get Timezone Offset for San Francisco

Use LocationIQ's timezone API to get the timezone offset for different cities with the input of coordinates.

• San Francisco: (37.774929,-122.419416)

https://eu1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=37.774929&lon=-122.419416×tamp=1718362800000

API Output:

{
  "timezone": {
    "name": "America/Los_Angeles",
    "now_in_dst": 0,
    "offset_sec": -28800,
    "short_name": "PST"
  }
}

name: Timezone identifier for San Francisco.
offset_sec: Timezone offset in seconds (negative for west of UTC).
now_in_dst: Indicates whether daylight saving time (DST) is currently in effect (0 for no).

3. Calculate Local Time for San Francisco

Original Meeting Time in London = 11:00 AM (New York) + (-28,800 seconds) = 3:00 AM (San Francisco)

So, for San Francisco, the local meeting time would be 3:00 AM on the 14th of June, 2024

Global Time Coordination with Timezone API

Here's a step-by-step guide that shows how to calculate the corresponding local time for a meeting in New York at 11 am on November 14, 2024, for San Francisco, London, Cape Town, Singapore & Japan

1. Get the Timezone Data for New York (Meeting Location):

Use LocationIQ's API to get the timezone data for New York (latitude: 40.7128, longitude: -74.0060) using your API key.

Sample API Request:

https://us1.locationiq.com/v1/timezone?key=YOUR_ACCESS_TOKEN&lat=40.7128&lon=-74.0060

2. Calculate Meeting Time in New York

API Output:

{
  "timezone": {
    "name": "America/New_York",
    "now_in_dst": 0,
    "offset_sec": -18000,
    "short_name": "EST"
  }
}

From the output for New York, extract the timezone offset in seconds. In this case, the offset is -18000 seconds (5 hours behind UTC).

• Meeting time in UTC: 11 am on November 14, 2024.
• Apply the offset of -18000 seconds.
• New York meeting time: UTC time + offset = 11 am UTC - 18000 seconds = 6 am New York time.

3. Calculate Meeting Time for Other Locations:

Perform similar calculations for San Francisco, London, Cape Town, Singapore & Japan using their respective timezone offsets.