Time Unit Converter API Documentation

Overview

The Time Unit Converter API allows you to convert time values between different units (seconds, minutes, hours, days, and weeks) with optional multipliers. This is useful for time calculations, scheduling, and unit standardization.

Conversion Rates (to seconds):

Seconds: 1 (base unit)
Minutes: 60 seconds
Hours: 3,600 seconds
Days: 86,400 seconds
Weeks: 604,800 seconds

Key Features

RESTful design with JSON input/output
CORS enabled for cross-origin requests
Support for all common time units
Optional multiplier for scaling values
Single request returns all unit conversions
Results rounded to 1 decimal place
Self-documenting API with info endpoint

Getting Started

Base URL

https://www.promptbox.cn/api/time.php

Authentication

This API does not require authentication. All endpoints are publicly accessible.

Content Type

All requests and responses use JSON format. Include the following header in your requests:

Content-Type: application/json

Rate Limiting

Currently, there are no rate limits imposed on this API. However, please use it responsibly.

API Endpoints

POST Convert Time Units

POST /time.php?action=convert

Description

Converts a time value from one unit to all other supported units. Optionally applies a multiplier to scale the input value.

Request Body

Parameter	Type	Required	Description
value	number	Required	The time value to convert
fromUnit	string	Required	Source unit: "seconds", "minutes", "hours", "days", or "weeks"
multiplier	number	Optional	Multiplier to apply to the value (default: 1, must be > 0)

Request Example

{
  "value": 2,
  "fromUnit": "hours",
  "multiplier": 1.5
}

Success Response (200 OK)

{
  "success": true,
  "data": {
    "input": {
      "value": 2,
      "fromUnit": "hours",
      "multiplier": 1.5
    },
    "valueInSeconds": 10800,
    "conversions": {
      "seconds": 10800,
      "minutes": 180,
      "hours": 3,
      "days": 0.1,
      "weeks": 0
    }
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
data.input	object	Echo of the input parameters
data.valueInSeconds	number	Total value converted to seconds (rounded to 1 decimal)
data.conversions	object	Converted values for all units (rounded to 1 decimal)

Note: The multiplier is applied to the input value before conversion. For example, 2 hours × 1.5 = 3 hours = 10,800 seconds.

GET Get API Information

GET /time.php?action=info

Description

Returns comprehensive information about the API, including available endpoints, conversion rates, and usage examples.

Request Parameters

None required.

Success Response (200 OK)

{
  "success": true,
  "data": {
    "api_name": "Time Unit Converter API",
    "version": "1.0.0",
    "description": "Convert between time units...",
    "endpoints": [...],
    "conversion_rates": {...}
  }
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests.

HTTP Status Codes

Status Code	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Invalid request parameters or data
405	Method Not Allowed	HTTP method not supported for this endpoint
500	Internal Server Error	Server encountered an unexpected error

Error Response Format

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common Error Scenarios

Invalid JSON

{
  "success": false,
  "error": "Invalid JSON input."
}

Missing Required Parameters

{
  "success": false,
  "error": "Missing required parameters: 'value' and 'fromUnit'."
}

Invalid Unit

{
  "success": false,
  "error": "Invalid fromUnit. Must be one of: seconds, minutes, hours, days, weeks."
}

Invalid Multiplier

{
  "success": false,
  "error": "Multiplier must be greater than 0."
}

Wrong HTTP Method

{
  "success": false,
  "error": "Method not allowed. Use POST for convert endpoint."
}

Usage Examples

Example 1: Simple Conversion (30 minutes)

Scenario: Convert 30 minutes to all other time units.

cURL Request

curl -X POST "https://www.promptbox.cn/api/time.php?action=convert" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 30,
    "fromUnit": "minutes"
  }'

JavaScript (Fetch API)

const response = await fetch('https://www.promptbox.cn/api/time.php?action=convert', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    value: 30,
    fromUnit: 'minutes'
  })
});

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

Python (requests library)

import requests
import json

url = "https://www.promptbox.cn/api/time.php?action=convert"
payload = {
    "value": 30,
    "fromUnit": "minutes"
}

response = requests.post(url, json=payload)
data = response.json()
print(data)

Response

{
  "success": true,
  "data": {
    "input": {
      "value": 30,
      "fromUnit": "minutes",
      "multiplier": 1
    },
    "valueInSeconds": 1800,
    "conversions": {
      "seconds": 1800,
      "minutes": 30,
      "hours": 0.5,
      "days": 0,
      "weeks": 0
    }
  }
}

Example 2: Conversion with Multiplier

Scenario: Convert 2 hours with a 1.5x multiplier (equivalent to 3 hours).

Request

{
  "value": 2,
  "fromUnit": "hours",
  "multiplier": 1.5
}

Response

{
  "success": true,
  "data": {
    "input": {
      "value": 2,
      "fromUnit": "hours",
      "multiplier": 1.5
    },
    "valueInSeconds": 10800,
    "conversions": {
      "seconds": 10800,
      "minutes": 180,
      "hours": 3,
      "days": 0.1,
      "weeks": 0
    }
  }
}

Example 3: Large Values (2 weeks)

Scenario: Convert 2 weeks to see all smaller time units.

Request

{
  "value": 2,
  "fromUnit": "weeks"
}

Response

{
  "success": true,
  "data": {
    "input": {
      "value": 2,
      "fromUnit": "weeks",
      "multiplier": 1
    },
    "valueInSeconds": 1209600,
    "conversions": {
      "seconds": 1209600,
      "minutes": 20160,
      "hours": 336,
      "days": 14,
      "weeks": 2
    }
  }
}

Example 4: Getting API Information

cURL Request

curl -X GET "https://www.promptbox.cn/api/time.php?action=info"

JavaScript (Fetch API)

const response = await fetch('https://www.promptbox.cn/api/time.php?action=info');
const data = await response.json();
console.log(data);

Try It Out

Test the API directly from this page. Enter your values below and click "Convert".

Input Parameters

Value:

From Unit:

Multiplier:

Response:

Response will appear here...

Best Practices

Use appropriate units: Choose the unit that makes the most sense for your use case to minimize rounding errors.
Handle multipliers carefully: Ensure multipliers are positive numbers greater than 0.
Check for rounding: Results are rounded to 1 decimal place. For precise calculations, consider working with the valueInSeconds field.
Error handling: Always check the 'success' field in responses and handle errors gracefully.
Unit case sensitivity: Unit names are case-insensitive, but it's best practice to use lowercase for consistency.
Batch conversions: The API returns all unit conversions in a single request, eliminating the need for multiple calls.
Decimal values: The API accepts decimal values for both the time value and multiplier (e.g., 2.5 hours).

Use Cases

Project Management

Convert task durations between different time units for scheduling and planning applications.

Fitness & Health

Calculate workout durations, rest periods, and activity tracking in various time formats.

Video & Media

Convert video lengths, audio durations, and streaming times between units.

Education

Teaching time conversions in math and science classes with real-time calculations.

Cooking & Recipes

Convert cooking times, marinating durations, and preparation times for recipes.

Time Tracking

Standardize logged work hours across different time-tracking systems and formats.

Integration Guide

Step 1: Set Up Your Environment

Ensure you have the API URL and can make HTTP requests from your application.

Step 2: Prepare Your Data

Structure your time conversion request with the value, source unit, and optional multiplier.

Step 3: Make the Request

Send a POST request to the convert endpoint with your JSON payload.

Step 4: Handle the Response

Check the 'success' field and extract the converted values from the response data.

Step 5: Error Handling

Implement proper error handling for network issues, validation errors, and edge cases.

Sample Integration (JavaScript)

async function convertTime(value, fromUnit, multiplier = 1) {
  try {
    const response = await fetch('https://www.promptbox.cn/api/time.php?action=convert', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ value, fromUnit, multiplier })
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const result = await response.json();

    if (result.success) {
      console.log('Conversions:', result.data.conversions);
      console.log('Value in seconds:', result.data.valueInSeconds);
      return result.data;
    } else {
      console.error('API Error:', result.error);
      return null;
    }
  } catch (error) {
    console.error('Request failed:', error);
    return null;
  }
}

// Usage examples
convertTime(30, 'minutes');
convertTime(2, 'hours', 1.5);
convertTime(1, 'weeks');

Sample Integration (Python)

import requests
import json

def convert_time(value, from_unit, multiplier=1):
    """Convert time units using the API"""
    url = "https://www.promptbox.cn/api/time.php?action=convert"
    payload = {
        "value": value,
        "fromUnit": from_unit,
        "multiplier": multiplier
    }
    
    try:
        response = requests.post(url, json=payload, timeout=10)
        response.raise_for_status()
        
        result = response.json()
        
        if result.get('success'):
            print(f"Conversions: {result['data']['conversions']}")
            return result['data']
        else:
            print(f"API Error: {result.get('error')}")
            return None
            
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

# Usage examples
convert_time(30, 'minutes')
convert_time(2, 'hours', 1.5)
convert_time(1, 'weeks')

Conversion Reference

Quick Reference Table

From	To Seconds	To Minutes	To Hours	To Days	To Weeks
1 Second	1	0.017	0.0003	0.00001	0
1 Minute	60	1	0.017	0.0007	0.0001
1 Hour	3,600	60	1	0.042	0.006
1 Day	86,400	1,440	24	1	0.143
1 Week	604,800	10,080	168	7	1

Common Conversions

90 minutes = 1.5 hours = 5,400 seconds
48 hours = 2 days = 2,880 minutes
72 hours = 3 days = 0.43 weeks
1,440 minutes = 24 hours = 1 day
10,080 minutes = 168 hours = 7 days = 1 week

Changelog

Version 1.0.0 (Current)

Initial release
POST /time.php?action=convert endpoint
GET /time.php?action=info endpoint
Support for seconds, minutes, hours, days, and weeks
Optional multiplier functionality
JSON request/response format
CORS support
Comprehensive error handling
Results rounded to 1 decimal place

FAQ

Q: What happens if I don't provide a multiplier?

A: The multiplier defaults to 1, meaning the value is converted as-is without any scaling.

Q: Can I use decimal values?

A: Yes! Both the value and multiplier accept decimal numbers (e.g., 2.5 hours, 1.5x multiplier).

Q: Why are some results showing 0?

A: Very small values may round to 0 when converted to larger units. For example, 1 second = 0.0 weeks. Check the valueInSeconds field for the precise intermediate value.

Q: What precision is used for calculations?

A: All calculations are performed with full floating-point precision, but results are rounded to 1 decimal place in the response.

Q: Do I need authentication?

A: No, the API is currently open and does not require authentication.

Q: Is the fromUnit parameter case-sensitive?

A: No, unit names are case-insensitive. "Minutes", "minutes", and "MINUTES" all work.

Q: Can I convert between specific units only?

A: The API always returns conversions for all supported units. Simply extract the specific unit you need from the conversions object.

Q: What's the maximum value I can convert?

A: There's no enforced maximum, but be aware of floating-point precision limits for extremely large numbers.

Q: Is CORS enabled?

A: Yes, the API has CORS enabled and can be called from any domain.

Q: How do I report bugs or request features?

A: Contact the API administrator or submit issues through your preferred channel.

Support & Contact

If you need assistance with the API or have questions not covered in this documentation:

Documentation Issues

If you find errors or unclear sections in this documentation, please report them.

Technical Support

For technical issues or integration help, contact your API administrator.

Feature Requests

Have an idea for improving the API? We'd love to hear your suggestions!