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&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

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

Timezone object

📘

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

1. Base time (London): 10:00 AM BST
2. Convert London time to UTC: 10:00 AM BST - 1 hour = 09:00 AM UTC
3. 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.