Timezone by IP API: The Complete Guide

Need to detect your users' timezone for scheduling or personalization? This guide covers everything you need to know about timezone detection via IP, including DST handling, accuracy, and implementation examples.

What is Timezone Detection?

Timezone detection by IP uses the geographic location associated with an IP address to determine the most likely timezone. This allows applications to display times in the user's local timezone without requiring manual input.

For example, an IP from New York would resolve to America/New_York (Eastern Time).

Timezone Data Explained

Timezone information includes several components:

Using the Timezone by IP API

TinyFn provides an endpoint to detect timezone from IP:

GET https://api.tinyfn.io/v1/geo/timezone?ip=8.8.8.8
Headers: X-API-Key: your-api-key

{
  "ip": "8.8.8.8",
  "timezone": {
    "id": "America/Los_Angeles",
    "abbreviation": "PST",
    "utc_offset": "-08:00",
    "utc_offset_seconds": -28800
  },
  "dst": {
    "active": false,
    "abbreviation": "PDT",
    "offset": "-07:00"
  },
  "current_time": "2024-01-15T10:30:45-08:00"
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/geo/timezone',  // Uses caller's IP
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const data = await response.json();

console.log(`Timezone: ${data.timezone.id}`);
console.log(`Current offset: ${data.timezone.utc_offset}`);
console.log(`DST active: ${data.dst.active}`);

// Format a date in user's timezone
const userDate = new Date().toLocaleString('en-US', {
  timeZone: data.timezone.id
});

Python

import requests
from datetime import datetime
import pytz

def get_user_timezone(ip_address=None):
    url = 'https://api.tinyfn.io/v1/geo/timezone'
    params = {'ip': ip_address} if ip_address else {}

    response = requests.get(
        url,
        params=params,
        headers={'X-API-Key': 'your-api-key'}
    )
    return response.json()

# Get timezone for visitor
tz_info = get_user_timezone()
timezone = pytz.timezone(tz_info['timezone']['id'])

# Convert UTC time to user's timezone
utc_time = datetime.utcnow().replace(tzinfo=pytz.UTC)
local_time = utc_time.astimezone(timezone)
print(f"Local time: {local_time}")

cURL

# Specific IP
curl "https://api.tinyfn.io/v1/geo/timezone?ip=203.0.113.50" \
  -H "X-API-Key: your-api-key"

# Auto-detect (your IP)
curl "https://api.tinyfn.io/v1/geo/timezone" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Scheduling: Show meeting times in user's local timezone
• Notifications: Send alerts at appropriate local times
• Analytics: Understand when users are most active
• E-commerce: Display delivery estimates in local time
• Content Timing: Schedule posts for optimal local times

Best Practices

1. Use IANA IDs: Store timezone IDs, not offsets, for DST handling
2. Allow override: Let users manually select their timezone
3. Handle edge cases: Some regions have unusual DST rules
4. Cache appropriately: Timezone lookups can be cached per IP

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-geo": {
      "url": "https://api.tinyfn.io/mcp/geo/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all geolocation tools available via MCP in our Geolocation MCP Tools for AI Agents guide.