Timezone Converter API Guide

Overview

The Timezone Converter API allows you to convert times between different time zones with ease. It supports live updates, custom time input, and a powerful API.

Quick Start

# Get current time in New York
curl "https://blstmo.com/api/timezone-converter?timezone=America/New_York"

# Convert specific time to Tokyo
curl "https://blstmo.com/api/timezone-converter?timezone=Asia/Tokyo&time=2024-03-06T19:30:00Z"

Rate Limiting

The API is rate-limited to 120 requests per minute. If you exceed this limit, you will receive a 429 status code with an error message indicating that the rate limit has been exceeded.

Usage

To use the API, send a GET request to the following endpoint:

GET /api/timezone-converter?timezone=America/New_York&time=2023-03-06T12:00:00Z

Query Parameters

• timezone: The IANA time zone identifier (e.g., America/New_York).
• time: The time to convert, in ISO 8601 format (optional). If not provided, the current time will be used.

Response

The API returns a JSON object with the following fields:

• timezone: The requested time zone.
• time: The converted time in the requested time zone.
• timestamp: The Unix timestamp of the converted time.

Example

{
  "timezone": "America/New_York",
  "time": "08:00:00",
  "timestamp": 1678108800000
}

Error Handling

If an error occurs, the API will return a JSON object with an error field describing the issue.

Best Practices

• Cache responses to reduce the number of requests.
• Handle rate limit errors gracefully by retrying after a delay.

Support

For support, please contact our team at [email protected].

API Reference

Endpoint

GET https://blstmo.com/api/timezone-converter

Query Parameters

Response Format

{
  time: string;      // Current time in HH:mm:ss format
  date: string;      // Current date in yyyy-MM-dd format
  timezone: string;  // IANA timezone identifier
  name: string;      // Human-readable timezone name
  offset: number;    // UTC offset in hours
  timestamp: number; // Unix timestamp in milliseconds
}

Error Responses

Implementation Examples

JavaScript/TypeScript

async function getTimeInZone(timezone: string, time?: string) {
  const params = new URLSearchParams({ timezone });
  if (time) params.append('time', time);
  
  const response = await fetch(`https://blstmo.com/api/timezone-converter?${params}`);
  
  // Handle rate limiting
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    throw new Error(`Rate limit exceeded. Try again in ${retryAfter} seconds`);
  }
  
  const data = await response.json();
  
  if (!response.ok) {
    throw new Error(data.error);
  }
  
  return data;
}

// Example usage with error handling
try {
  // Get current time in New York
  const nyTime = await getTimeInZone('America/New_York');
  console.log('New York:', nyTime);
  
  // Convert specific time to Tokyo
  const tokyoTime = await getTimeInZone(
    'Asia/Tokyo',
    '2024-03-06T19:30:00Z'
  );
  console.log('Tokyo:', tokyoTime);
} catch (error) {
  if (error.message.includes('Rate limit exceeded')) {
    // Handle rate limiting
    console.error('Please wait before making more requests');
  } else {
    console.error('Error:', error.message);
  }
}

Python

import requests
from datetime import datetime
from typing import Optional, Dict, Any

def get_time_in_zone(timezone: str, time: Optional[str] = None) -> Dict[str, Any]:
    """
    Convert time between timezones using the API.
    
    Args:
        timezone: IANA timezone identifier (e.g., 'America/New_York')
        time: Optional ISO 8601 timestamp. Uses current time if not provided.
        
    Returns:
        Dict containing the converted time information.
        
    Raises:
        requests.exceptions.HTTPError: If the API request fails.
        Exception: If rate limit is exceeded.
    """
    params = {'timezone': timezone}
    if time:
        params['time'] = time
        
    response = requests.get(
        'https://blstmo.com/api/timezone-converter',
        params=params
    )
    
    // Handle rate limiting
    if response.status_code == 429:
        retry_after = response.headers.get('Retry-After', '60')
        raise Exception(f'Rate limit exceeded. Try again in {retry_after} seconds')
    
    response.raise_for_status()
    return response.json()

# Example usage with error handling
try:
    // Get current time in New York
    ny_time = get_time_in_zone('America/New_York')
    print('New York:', ny_time)
    
    // Convert specific time to Tokyo
    tokyo_time = get_time_in_zone(
        'Asia/Tokyo',
        '2024-03-06T19:30:00Z'
    )
    print('Tokyo:', tokyo_time)
except requests.exceptions.RequestException as e:
    print('API Error:', str(e))
except Exception as e:
    print('Error:', str(e))

Technical Details

Edge Runtime

The API runs on Cloudflare’s Edge network, providing:

• Low latency responses worldwide
• High availability and reliability
• Automatic SSL/TLS encryption
• DDoS protection

Rate Limiting Implementation

• Uses a simple in-memory counter
• Tracked per IP address
• 60-second sliding window
• Automatic cleanup of expired entries
• Efficient memory usage with Map data structure

Caching Strategy

• Responses are cached for 60 seconds
• OPTIONS requests are cached for 1 hour
• Cache headers are properly set for CDN optimization
• Cache-Control directives allow client-side caching

Security

• CORS enabled for cross-origin requests
• Rate limiting prevents abuse
• Input validation for all parameters
• Error messages don’t expose sensitive information

Support and Feedback

If you encounter any issues or have suggestions for improvement:

1. Check the error response for specific information
2. Review this documentation for best practices
3. Ensure you’re handling rate limits correctly
4. Contact us if you need higher rate limits

We’re constantly improving the API based on user feedback and usage patterns. Let us know how we can make it better for your use case.