Timezone
Get timezone information for any location by geographic coordinates or city name. Returns the IANA timezone identifier, UTC offset, current time, and DST status.
Overview
Use Cases
- Display local time for a given location
- Scheduling and calendar applications
- Travel and logistics platforms
- Location-aware notifications
Features
Lookup by latitude/longitude or city name
IANA timezone identifiers (e.g. "America/New_York")
DST detection for the current date
UTC offset in standard +HH:MM format
150+ major cities supported for city-based lookup
API Endpoints
Get Timezone
Returns timezone information for the given coordinates or city name. Provide either `city` or both `lat` and `lon`.
GET
https://requiems.xyz/v1/places/timezone
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| lat | number |
Optional | Latitude of the location (-90 to 90). Required when using coordinate-based lookup. |
| lon | number |
Optional | Longitude of the location (-180 to 180). Required when using coordinate-based lookup. |
| city | string |
Optional | City name for city-based lookup (e.g. 'Tokyo', 'London'). Required when not using coordinates. |
Try it out
Live DemoRequest
Latitude of the location (-90 to 90). Required when using coordinate-based lookup.
Longitude of the location (-180 to 180). Required when using coordinate-based lookup.
City name for city-based lookup (e.g. 'Tokyo', 'London'). Required when not using coordinates.
Sending request...
Response Fields
| Field | Type | Description |
|---|---|---|
| timezone | string |
IANA timezone identifier (e.g. "Europe/London", "Asia/Tokyo") |
| offset | string |
UTC offset in +HH:MM or -HH:MM format (e.g. '+05:30', '-05:00') |
| current_time | string |
Current time in UTC, formatted as RFC 3339 (e.g. "2024-12-15T14:30:00Z") |
| is_dst | boolean |
Whether the location is currently observing daylight saving time |
Code Examples
# Lookup by coordinates
curl "https://requiems.xyz/v1/places/timezone?lat=51.5&lon=-0.1" \
-H "requiems-api-key: YOUR_API_KEY"
# Lookup by city
curl "https://requiems.xyz/v1/places/timezone?city=Tokyo" \
-H "requiems-api-key: YOUR_API_KEY"import requests
# Lookup by coordinates
url = "https://requiems.xyz/v1/places/timezone"
headers = {"requiems-api-key": "YOUR_API_KEY"}
response = requests.get(url, params={"lat": 51.5, "lon": -0.1}, headers=headers)
print(response.json())
# Lookup by city
response = requests.get(url, params={"city": "Tokyo"}, headers=headers)
print(response.json())// Lookup by coordinates
const response = await fetch(
'https://requiems.xyz/v1/places/timezone?lat=51.5&lon=-0.1',
{ headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const data = await response.json();
console.log(data.data.timezone);
// Lookup by city
const cityResponse = await fetch(
'https://requiems.xyz/v1/places/timezone?city=Tokyo',
{ headers: { 'requiems-api-key': 'YOUR_API_KEY' } }
);
const cityData = await cityResponse.json();
console.log(cityData.data.timezone);require 'net/http'
require 'json'
# Lookup by coordinates
uri = URI('https://requiems.xyz/v1/places/timezone')
uri.query = URI.encode_www_form(lat: 51.5, lon: -0.1)
request = Net::HTTP::Get.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)
puts data['data']['timezone']Batch Timezone Lookup
Look up timezone information for up to 50 locations in a single request. Each item can specify a timezone name, city, or lat/lon coordinates. Priority is timezone name > city > coordinates. Results are returned in input order.
POST
https://requiems.xyz/v1/places/timezone/batch
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| items | array<object> |
Required | List of timezone lookup requests (1β50 items). |
| items[].timezone | string |
Optional | IANA timezone name (e.g. 'America/New_York'). Highest priority. |
| items[].city | string |
Optional | City name for city-based lookup. Used when timezone is not set. |
| items[].lat | number |
Optional | Latitude (-90 to 90). Used when neither timezone nor city is set. |
| items[].lon | number |
Optional | Longitude (-180 to 180). Used alongside lat for coordinate-based lookup. |
Try it out
Live DemoRequest
List of timezone lookup requests (1β50 items).
IANA timezone name (e.g. 'America/New_York'). Highest priority.
City name for city-based lookup. Used when timezone is not set.
Latitude (-90 to 90). Used when neither timezone nor city is set.
Longitude (-180 to 180). Used alongside lat for coordinate-based lookup.
Sending request...
Response Fields
| Field | Type | Description |
|---|---|---|
| results | array<object> |
Per-item results in input order. |
| results[].info.timezone | string |
IANA timezone identifier. |
| results[].info.offset | string |
UTC offset in +HH:MM or -HH:MM format. |
| results[].info.current_time | string |
Current time in UTC (RFC 3339). |
| results[].info.is_dst | boolean |
Whether daylight saving time is currently active. |
| results[].error | string |
Error message if this item failed (omitted on success). |
| total | integer |
Total number of items processed. |
Code Examples
curl -X POST https://requiems.xyz/v1/places/timezone/batch \
-H "requiems-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"items": [{"timezone": "America/New_York"}, {"city": "Tokyo"}, {"lat": 51.5, "lon": -0.1}]}'import requests
url = "https://requiems.xyz/v1/places/timezone/batch"
headers = {
"requiems-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"items": [
{"timezone": "America/New_York"},
{"city": "Tokyo"},
{"lat": 51.5, "lon": -0.1}
]
}
response = requests.post(url, headers=headers, json=payload)
for item in response.json()["data"]["results"]:
if item.get("info"):
print(item["info"]["timezone"], item["info"]["offset"])const response = await fetch('https://requiems.xyz/v1/places/timezone/batch', {
method: 'POST',
headers: {
'requiems-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
items: [
{ timezone: 'America/New_York' },
{ city: 'Tokyo' },
{ lat: 51.5, lon: -0.1 }
]
})
});
const { data } = await response.json();
data.results.forEach(item => {
if (item.info) console.log(item.info.timezone, item.info.offset);
});require 'net/http'
require 'json'
uri = URI('https://requiems.xyz/v1/places/timezone/batch')
request = Net::HTTP::Post.new(uri)
request['requiems-api-key'] = 'YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
items: [
{ timezone: 'America/New_York' },
{ city: 'Tokyo' },
{ lat: 51.5, lon: -0.1 }
]
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
data = JSON.parse(response.body)['data']
data['results'].each do |item|
puts "#{item['info']['timezone']}: #{item['info']['offset']}" if item['info']
endError Responses
validation_failed
The items array is missing, empty, or exceeds 50 items.
bad_request
The request body is missing or malformed.
Frequently Asked Questions
Use coordinates (lat/lon) for precise lookups anywhere in the world. Use the city name for a quick lookup when you have a well-known city name. Coordinate-based lookup works for any point on Earth, while city-based lookup is limited to the ~150+ cities in our database.
No. City names are normalised to lowercase before lookup, so "Tokyo", "TOKYO", and "tokyo" all work.
is_dst indicates whether the location is currently observing Daylight Saving Time. For locations that do not use DST (e.g. Japan, most of Africa), this is always false.
The offset field uses the format +HH:MM or -HH:MM (e.g. '+05:30' for India, '-05:00' for US Eastern Standard Time).
All timezone identifiers follow the IANA Time Zone Database standard (also known as the Olson database), e.g. 'America/New_York', 'Europe/London', 'Asia/Tokyo'.