API Documentation

Complete API reference with request examples using fetch and curl

API Overview

TimeSpeaker provides two main endpoints for generating and retrieving time audio files:

/api/audio - Generate or retrieve time audio
/api/session - Get current session information

GET /api/audio

Generates or retrieves cached audio of the current time.

Query Parameters

language

Language code (pt-BR, en, es). Default: en

timezone

Timezone identifier (e.g., America/Sao_Paulo). Default: UTC

Headers

audio/mpeg returns audio file
application/json returns JSON with URL

Authorization (optional)

Bearer token for higher rate limits

JavaScript (fetch) Example

// Get audio file
fetch('/api/audio?language=pt-BR&timezone=America/Sao_Paulo', {
    headers: {
        'Accept': 'audio/mpeg'
    }
})
.then(response => response.blob())
.then(blob => {
    const audio = new Audio(URL.createObjectURL(blob));
    audio.play();
})
.catch(error => console.error('Error:', error));

// Get JSON response with URL
fetch('/api/audio?language=en&timezone=UTC', {
    headers: {
        'Accept': 'application/json'
    }
})
.then(response => response.json())
.then(data => {
    console.log('Audio URL:', data.url);
    console.log('Language:', data.language);
    console.log('Timezone:', data.timezone);
    console.log('Time:', data.time);
})
.catch(error => console.error('Error:', error));

cURL Example

# Download audio file
curl -H "Accept: audio/mpeg" \
     "http://localhost:3000/api/audio?language=pt-BR&timezone=America/Sao_Paulo" \
     --output time.mp3

# Get JSON response
curl -H "Accept: application/json" \
     "http://localhost:3000/api/audio?language=en&timezone=UTC"

# With authentication
curl -H "Accept: audio/mpeg" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "App-Id: YOUR_UUID" \
     "http://localhost:3000/api/audio?language=es&timezone=Europe/Madrid"

Response Examples

JSON Response (Accept: application/json):

{
  "url": "/audio-cache/abc123def456.mp3",
  "language": "pt-BR",
  "timezone": "America/Sao_Paulo",
  "time": "14:30"
}

Audio Response (Accept: audio/mpeg):

Binary audio file (MP3 format)

GET /api/session

Returns current session information based on request context.

Query Parameters

language (optional)

Override language detection

timezone (optional)

Override timezone detection

JavaScript (fetch) Example

// Get session info with auto-detection
fetch('/api/session')
.then(response => response.json())
.then(data => {
    console.log('Detected Language:', data.language);
    console.log('Detected Timezone:', data.timezone);
    console.log('Current Time:', data.currentTime);
})
.catch(error => console.error('Error:', error));

// Override detection
fetch('/api/session?language=pt-BR&timezone=America/Sao_Paulo')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

cURL Example

# Auto-detect session
curl "http://localhost:3000/api/session"

# With overrides
curl "http://localhost:3000/api/session?language=es&timezone=Europe/Madrid"

# With Accept-Language header
curl -H "Accept-Language: pt-BR" \
     "http://localhost:3000/api/session"

Response Example

{
  "language": "pt-BR",
  "timezone": "America/Sao_Paulo",
  "currentTime": "2025-11-30T14:30:00-03:00"
}

Rate Limiting

Unauthenticated Requests

5 requests per minute per IP address

Authenticated Requests

20 requests per minute per IP address

429 Too Many Requests: When rate limit is exceeded, the API will return HTTP 429 with a message indicating the limit has been reached.

Supported Languages & Timezones

Languages

pt-BR - Português (Brasil)
en - English
es - Español

Common Timezones

UTC
America/Sao_Paulo
America/New_York
Europe/London
Asia/Tokyo
+ All IANA timezone identifiers