Relative Time API: The Complete Guide to Human-Friendly Time Formatting

Need to display timestamps in a user-friendly way? This guide covers everything you need to know about formatting dates as relative time ("2 hours ago", "in 3 days") via API, including localization and implementation examples.

What is Relative Time?

Relative time formatting expresses timestamps relative to the current moment, making them more intuitive and user-friendly. For example, "January 15, 2024 3:45 PM" becomes "2 hours ago" or "yesterday".

Users understand "5 minutes ago" much faster than "January 15, 2024 4:32:15 PM UTC".

Formatting Rules

Relative time uses different units based on the time difference:

Recent Past/Future

Within a minute: "just now", "in a moment". Within an hour: "5 minutes ago", "in 45 minutes".

Same Day/Yesterday/Tomorrow

"2 hours ago", "yesterday", "tomorrow" - familiar terms for recent times.

Longer Periods

"3 days ago", "2 weeks ago", "last month", "2 years ago" - progressively less precise.

Using the Relative Time API

TinyFn provides a simple endpoint to format relative time:

GET https://api.tinyfn.io/v1/format/relative-time?timestamp=2024-01-15T10:30:00Z
Headers: X-API-Key: your-api-key

{
  "timestamp": "2024-01-15T10:30:00Z",
  "relative": "2 hours ago",
  "direction": "past",
  "unit": "hours",
  "value": 2,
  "locale": "en"
}

Parameters

Code Examples

JavaScript / Node.js

// Get relative time for a past timestamp
const response = await fetch(
  'https://api.tinyfn.io/v1/format/relative-time?timestamp=2024-01-15T10:30:00Z',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { relative, direction } = await response.json();
console.log(relative);   // 2 hours ago
console.log(direction);  // past

// Get relative time for a future timestamp
const futureResponse = await fetch(
  'https://api.tinyfn.io/v1/format/relative-time?timestamp=2024-01-20T10:30:00Z',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { relative: futureRelative } = await futureResponse.json();
console.log(futureRelative); // in 5 days

Python

import requests

# Get relative time
response = requests.get(
    'https://api.tinyfn.io/v1/format/relative-time',
    params={'timestamp': '2024-01-15T10:30:00Z'},
    headers={'X-API-Key': 'your-api-key'}
)
data = response.json()
print(data['relative'])   # 2 hours ago
print(data['direction'])  # past

# Get relative time in German
response = requests.get(
    'https://api.tinyfn.io/v1/format/relative-time',
    params={'timestamp': '2024-01-15T10:30:00Z', 'locale': 'de'},
    headers={'X-API-Key': 'your-api-key'}
)
print(response.json()['relative'])  # vor 2 Stunden

cURL

# Get relative time
curl "https://api.tinyfn.io/v1/format/relative-time?timestamp=2024-01-15T10:30:00Z" \
  -H "X-API-Key: your-api-key"

# Get relative time in French
curl "https://api.tinyfn.io/v1/format/relative-time?timestamp=2024-01-15T10:30:00Z&locale=fr" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Social Media: Show when posts were created ("5 minutes ago")
• Notifications: Display when events occurred
• Comments: Show comment timestamps in discussions
• Activity Feeds: Display user activity timing
• Scheduling: Show "in 2 hours" for upcoming events

Best Practices

1. Update dynamically: Refresh "5 minutes ago" as time passes
2. Show exact time on hover: Let users see full timestamp if needed
3. Switch to absolute dates: Use "Jan 15" for older items
4. Localize properly: Different languages have different grammar rules

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-format": {
      "url": "https://api.tinyfn.io/mcp/format/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all formatting tools available via MCP in our Formatting MCP Tools for AI Agents guide.