Skip to main content
GET
/
v1
/
timezone
Get Timezone
curl --request GET \
  --url https://api.bookovia.com/v1/timezone \
  --header 'X-API-Key: <api-key>'
{
  "success": true,
  "timezone": "<string>",
  "region": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.bookovia.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Timezone endpoint returns the IANA timezone identifier for a given coordinate. It uses administrative boundary data to map locations to their corresponding timezones, essential for scheduling, datetime conversions, and user experience localization.

​
Authentication

This endpoint requires authentication via API key in the X-API-Key header. Required permissions: geocoding:read

​
Request

​
lat
number
required
Latitude coordinate (-90 to 90)
​
lon
number
required
Longitude coordinate (-180 to 180)

​
Request Example

curl -X GET "https://api.bookovia.com/v1/timezone?lat=40.7128&lon=-74.0060" \
  -H "X-API-Key: bkv_test_your_api_key_here"

​
Response

​
success
boolean
Indicates whether the request was successful
​
timezone
string
IANA timezone identifier (e.g., “America/New_York”, “America/Los_Angeles”)Can be used with standard datetime libraries for conversions
​
region
string
ISO 3166-2 region code used for timezone lookup (e.g., “US-NY”)

​
Response Example

{
  "success": true,
  "timezone": "America/New_York",
  "region": "US-NY"
}

​
Supported Timezones

Current implementation covers major US timezones:
Region CodeTimezoneUTC Offset (Standard)
US-NYAmerica/New_YorkUTC-5
US-CAAmerica/Los_AngelesUTC-8
US-TXAmerica/ChicagoUTC-6
US-FLAmerica/New_YorkUTC-5
US-ILAmerica/ChicagoUTC-6
US-WAAmerica/Los_AngelesUTC-8
US-MAAmerica/New_YorkUTC-5
US-AZAmerica/PhoenixUTC-7 (no DST)
US-NVAmerica/Los_AngelesUTC-8
US-COAmerica/DenverUTC-7
Default timezone is America/New_York for unmapped regions. Additional timezone mappings can be added on request.

​
Use Cases

Convert UTC timestamps to local time for display in user interfaces.
Schedule deliveries, appointments, or events in the correct local timezone.
Display trip timestamps in the timezone where the trip occurred.
Determine if a location is currently within business hours based on local time.
Aggregate time-series data by local business hours rather than UTC.

​
Error Handling

Status CodeErrorDescription
400lat and lon are requiredMissing coordinates
401API key requiredMissing authentication
500search errorInternal boundary lookup error

​
Performance

  • Average Response Time: <100ms
  • Method: Region-based lookup via boundaries
  • Fallback: Returns America/New_York if region unmapped

​
Best Practices

Use with datetime libraries: The returned IANA timezone string works with Python’s pytz, JavaScript’s Intl.DateTimeFormat, and Go’s time.LoadLocation().
Cache by region: If you’re processing many coordinates in the same area, cache the timezone by region code to reduce API calls.
Handle DST: IANA timezones automatically handle Daylight Saving Time when used with standard libraries.

​
Example: Convert UTC to Local Time

// Get timezone for NYC
const resp = await fetch('https://api.bookovia.com/v1/timezone?lat=40.7128&lon=-74.0060', {
  headers: { 'X-API-Key': 'bkv_test_key' }
});
const { timezone } = await resp.json();

// Convert UTC to local time
const utcDate = new Date('2026-04-25T15:30:00Z');
const localTime = utcDate.toLocaleString('en-US', { timeZone: timezone });
// Output: "4/25/2026, 11:30:00 AM" (EDT)