Skip to content

Timezone

The Timezone endpoint provides access to user timezone information, including timezone offset data for a range of dates.

GET /timezone/{user_id}

Parameters

Name Type In Description
user_id UUID Path The unique identifier for the user.
start_date Date Query The start date for the range (format: YYYY-MM-DD).
end_date Date Query The end date for the range (format: YYYY-MM-DD).

Responses

200 OK
[
    {
        "date": "2025-05-01",
        "timezone": {
            "offset_minutes": 120,
            "found_date": "2024-04-29"
        }
    },
    {
        "date": "2025-05-02",
        "timezone": {
            "offset_minutes": 120,
            "found_date": "2024-04-29"
        }
    }
]
404 Not Found
{
    "detail": "Timezone not found for user between {start_date} and {end_date} in database"
}

Example Request

cURL
curl -X GET "https://research-api.nowatch.com/timezone/123e4567-e89b-12d3-a456-426614174000?start_date=2025-05-01&end_date=2025-05-07" \
  -H "X-API-KEY: YOUR_API_KEY"

Response Details

  • date: The requested date for which timezone information is provided.
  • timezone: Object containing timezone details:
    • offset_minutes: The timezone offset in minutes from UTC. Positive values indicate timezones ahead of UTC, negative values indicate timezones behind UTC. May be null if no timezone data is found for that date.
    • found_date: The actual date on which the timezone data was found (may differ from the requested date if searching backwards).

Notes

  • The endpoint searches for timezone data up to 14 days back from each requested date if no data is found for the exact date.
  • For dates where no timezone data is found, the offset_minutes will be null and found_date will be null.
  • The endpoint is rate limited to 2 requests per second.
  • The date range is inclusive of both start_date and end_date.