Copy page

Copy page as Markdown for LLMs

View as Markdown

View this page as plain text


Open in ChatGPT

Ask ChatGPT about this page

Open in Claude

Ask Claude about this page

Timezone API

Introducing the Timezone API, a simple and reliable way to fetch timezone information for a geographical location using its location ID and an optional date and time.

The API allows you to retrieve the timezone of a selected location by passing its place_id. You can also provide a specific date and time to retrieve timezone information for that moment.


API Endpoint

POST https://geolocation.divineapi.com/timezone

Guide: Use this endpoint to retrieve timezone information for a given geographical location.


Headers

NameTypeDescription
Authorization*StringYour API Access Token. Example: Bearer {token}

Fields marked with * are mandatory.


Request Body

NameTypeDescription
api_key*StringYour API key from the DivineAPI dashboard.
place_id*IntegerUnique location ID obtained from the Location API.
dayIntegerDay of the month (1–31). Optional.
monthIntegerMonth of the year (1–12). Optional.
yearIntegerYear for which timezone information is required. Optional.
hourIntegerHour of the day (24-hour format). Optional.
minIntegerMinute (0–59). Optional.
secIntegerSecond (0–59). Optional.

Fields marked with * are mandatory.

Note: The place_id can be obtained from the Location API.

Date and Time Behavior:

If day, month, year, hour, min, and sec are provided, the API returns timezone information for the specified date and time.

If these parameters are not provided, the API automatically uses the current date and time to determine the timezone.


200: OK 

{
    "status": "success",
    "code": 200,
    "message": "Request successful",
    "data": {
        "place": {
            "place_id": 3824300,
            "name": "Xiloxúchitl",
            "full_name": "Xiloxúchitl, Veracruz, Mexico",
            "country": "MX",
            "admin1": "Veracruz",
            "latitude": 21.34639,
            "longitude": -98.2706,
            "timezone": "America/Mexico_City"
        },
        "timezone": "America/Mexico_City",
        "local_datetime": "2026-11-18 05:54:24",
        "utc_datetime": "2026-11-18 11:54:24",
        "timezone_value": -6,
        "utc_offset": "-06:00",
        "is_dst": false,
        "ambiguous": false
    },
    "attribution": "Place data © GeoNames (geonames.org), CC BY 4.0"
}

Example Code Implementations

Below are example implementations in various programming environments.


cURL

curl --location 'https://geolocation.divineapi.com/timezone' \
--header 'Authorization: Bearer {YOUR_AUTH_TOKEN}' \
--form 'api_key="{YOUR_API_KEY}"' \
--form 'place_id="3824300"' \
--form 'day="15"' \
--form 'month="7"' \
--form 'year="1990"' \
--form 'hour="14"' \
--form 'min="30"' \
--form 'sec="0"'
curl -X POST "https://geolocation.divineapi.com/timezone" \
  -H "Authorization: Bearer {Your Auth Token}" \
  --form 'api_key="{Your API Key}"' \
  --form 'place_id="3824300"' \
  --form 'day="15"' \
  --form 'month="7"' \
  --form 'year="1990"' \
  --form 'hour="14"' \
  --form 'min="30"' \
  --form 'sec="0"'
const FormData = require('form-data');
const axios = require('axios');

const form = new FormData();
form.append('api_key', '{Your API Key}');
form.append('place_id', '3824300');
form.append('day', '15');
form.append('month', '7');
form.append('year', '1990');
form.append('hour', '14');
form.append('min', '30');
form.append('sec', '0');

const response = await axios.post('https://geolocation.divineapi.com/timezone', form, {
  headers: {
    ...form.getHeaders(),
    'Authorization': 'Bearer {Your Auth Token}',
  }
});

console.log(response.data);
import requests

url = "https://geolocation.divineapi.com/timezone"
headers = {
    "Authorization": "Bearer {Your Auth Token}",
}
payload = {
    "api_key": "{Your API Key}",
    "place_id": "3824300",
    "day": "15",
    "month": "7",
    "year": "1990",
    "hour": "14",
    "min": "30",
    "sec": "0",
}

response = requests.post(url, headers=headers, data=payload)

print(response.json())
const formData = new FormData();
formData.append('api_key', '{Your API Key}');
formData.append('place_id', '3824300');
formData.append('day', '15');
formData.append('month', '7');
formData.append('year', '1990');
formData.append('hour', '14');
formData.append('min', '30');
formData.append('sec', '0');

const response = await fetch('https://geolocation.divineapi.com/timezone', {
  method: 'POST',
  headers: {
      'Authorization': "Bearer {Your Auth Token}",
    },
  body: formData,
});

const data = await response.json();
console.log(data);
<?php

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://geolocation.divineapi.com/timezone', [
    'headers' => [
        'Authorization' => 'Bearer {Your Auth Token}',
    ],
    'multipart' => [
        ['name' => 'api_key', 'contents' => '{Your API Key}'],
        ['name' => 'place_id', 'contents' => '3824300'],
        ['name' => 'day', 'contents' => '15'],
        ['name' => 'month', 'contents' => '7'],
        ['name' => 'year', 'contents' => '1990'],
        ['name' => 'hour', 'contents' => '14'],
        ['name' => 'min', 'contents' => '30'],
        ['name' => 'sec', 'contents' => '0'],
    ],
]);

echo $response->getBody();
package main

import (
    "bytes"
    "fmt"
    "mime/multipart"
    "net/http"
    "io"
)

func main() {
    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    writer.WriteField("api_key", "{Your API Key}")
    writer.WriteField("place_id", "3824300")
    writer.WriteField("day", "15")
    writer.WriteField("month", "7")
    writer.WriteField("year", "1990")
    writer.WriteField("hour", "14")
    writer.WriteField("min", "30")
    writer.WriteField("sec", "0")
    writer.Close()

    req, _ := http.NewRequest("POST", "https://geolocation.divineapi.com/timezone", body)
    req.Header.Set("Content-Type", writer.FormDataContentType())
    req.Header.Set("Authorization", "Bearer {Your Auth Token}")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    body2, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body2))
}
import okhttp3.*;
import java.io.IOException;

public class Main {
    public static void main(String[] args) throws IOException {
        OkHttpClient client = new OkHttpClient();

        RequestBody body = new MultipartBody.Builder()
            .setType(MultipartBody.FORM)
            .addFormDataPart("api_key", "{Your API Key}")
            .addFormDataPart("place_id", "3824300")
            .addFormDataPart("day", "15")
            .addFormDataPart("month", "7")
            .addFormDataPart("year", "1990")
            .addFormDataPart("hour", "14")
            .addFormDataPart("min", "30")
            .addFormDataPart("sec", "0")
            .build();

        Request request = new Request.Builder()
            .url("https://geolocation.divineapi.com/timezone")
            .post(body)
            .addHeader("Authorization", "Bearer {Your Auth Token}")
            .build();

        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}
import Foundation

let url = URL(string: "https://geolocation.divineapi.com/timezone")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("Bearer {Your Auth Token}", forHTTPHeaderField: "Authorization")

let boundary = "Boundary-\(UUID().uuidString)"
request.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")

var bodyData = Data()
bodyData.append("--\(boundary)\r\n".data(using: .utf8)!)
bodyData.append("Content-Disposition: form-data; name=\"api_key\"\r\n\r\n".data(using: .utf8)!)
bodyData.append("{Your API Key}\r\n".data(using: .utf8)!)
bodyData.append("--\(boundary)\r\n".data(using: .utf8)!)
bodyData.append("Content-Disposition: form-data; name=\"place_id\"\r\n\r\n".data(using: .utf8)!)
bodyData.append("3824300\r\n".data(using: .utf8)!)
bodyData.append("--\(boundary)\r\n".data(using: .utf8)!)
bodyData.append("Content-Disposition: form-data; name=\"day\"\r\n\r\n".data(using: .utf8)!)
bodyData.append("15\r\n".data(using: .utf8)!)
bodyData.append("--\(boundary)\r\n".data(using: .utf8)!)
bodyData.append("Content-Disposition: form-data; name=\"month\"\r\n\r\n".data(using: .utf8)!)
bodyData.append("7\r\n".data(using: .utf8)!)
bodyData.append("--\(boundary)\r\n".data(using: .utf8)!)
bodyData.append("Content-Disposition: form-data; name=\"year\"\r\n\r\n".data(using: .utf8)!)
bodyData.append("1990\r\n".data(using: .utf8)!)
bodyData.append("--\(boundary)\r\n".data(using: .utf8)!)
bodyData.append("Content-Disposition: form-data; name=\"hour\"\r\n\r\n".data(using: .utf8)!)
bodyData.append("14\r\n".data(using: .utf8)!)
bodyData.append("--\(boundary)\r\n".data(using: .utf8)!)
bodyData.append("Content-Disposition: form-data; name=\"min\"\r\n\r\n".data(using: .utf8)!)
bodyData.append("30\r\n".data(using: .utf8)!)
bodyData.append("--\(boundary)\r\n".data(using: .utf8)!)
bodyData.append("Content-Disposition: form-data; name=\"sec\"\r\n\r\n".data(using: .utf8)!)
bodyData.append("0\r\n".data(using: .utf8)!)
bodyData.append("--\(boundary)--\r\n".data(using: .utf8)!)
request.httpBody = bodyData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    }
}
task.resume()
import okhttp3.*

fun main() {
    val client = OkHttpClient()

    val body = MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart("api_key", "{Your API Key}")
        .addFormDataPart("place_id", "3824300")
        .addFormDataPart("day", "15")
        .addFormDataPart("month", "7")
        .addFormDataPart("year", "1990")
        .addFormDataPart("hour", "14")
        .addFormDataPart("min", "30")
        .addFormDataPart("sec", "0")
        .build()

    val request = Request.Builder()
        .url("https://geolocation.divineapi.com/timezone")
        .post(body!!)
        .addHeader("Authorization", "Bearer {Your Auth Token}")
        .build()

    client.newCall(request).execute().use { response ->
        println(response.body?.string())
    }
}
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program {
    static async Task Main() {
        using var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer {Your Auth Token}");

        var content = new MultipartFormDataContent();
        content.Add(new StringContent("{Your API Key}"), "api_key");
        content.Add(new StringContent("3824300"), "place_id");
        content.Add(new StringContent("15"), "day");
        content.Add(new StringContent("7"), "month");
        content.Add(new StringContent("1990"), "year");
        content.Add(new StringContent("14"), "hour");
        content.Add(new StringContent("30"), "min");
        content.Add(new StringContent("0"), "sec");

        var response = await client.PostAsync("https://geolocation.divineapi.com/timezone", content);
        var result = await response.Content.ReadAsStringAsync();
        Console.WriteLine(result);
    }
}
Response 200
{
    "status": "success",
    "code": 200,
    "message": "Request successful",
    "data": {
        "place": {
            "place_id": 3824300,
            "name": "Xiloxúchitl",
            "full_name": "Xiloxúchitl, Veracruz, Mexico",
            "country": "MX",
            "admin1": "Veracruz",
            "latitude": 21.34639,
            "longitude": -98.2706,
            "timezone": "America/Mexico_City"
        },
        "timezone": "America/Mexico_City",
        "local_datetime": "2026-11-18 05:54:24",
        "utc_datetime": "2026-11-18 11:54:24",
        "timezone_value": -6,
        "utc_offset": "-06:00",
        "is_dst": false,
        "ambiguous": false
    },
    "attribution": "Place data © GeoNames (geonames.org), CC BY 4.0"
}