📖 Overview
The Fortune Teller API provides random fortune predictions in multiple languages. With 52 unique fortunes covering various life aspects, it's perfect for entertainment apps, daily motivation services, or cultural applications.
🌍 Multilingual Support
Thai, Chinese (Simplified), and English language options
🎯 52 Unique Fortunes
Carefully curated predictions covering all aspects of life
🌱 Positive, Uplifting Content
Every fortune is kind, respectful and safe for all audiences
🎲 Random Selection
Cryptographically secure random fortune selection
🌍 Languages Returned in Every Response
Every fortune is returned as an object with three pre-translated fields. There is no single-language query parameter — clients pick the language on the client side.
🇹🇭 Thai
fortune.thai
🇨🇳 Chinese
fortune.chinese
🇺🇸 English
fortune.english
🌐 Base URL
🔐 Authentication
No authentication required. This is a public API that can be accessed without any API keys or tokens.
📡 API Endpoints
GET / Get Random Fortune
Retrieve a random fortune. Without any query parameter, the API uses random_int() over the number of available prediction files and returns the chosen one with all three language fields.
Parameters
This endpoint takes no parameters.
Example Request
GET /?id=N Get Specific Fortune by ID
Retrieve a specific fortune by its integer ID. IDs are 1-based and correspond to filenames under predictions/<id>.json.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id |
integer | Optional | random | Specific fortune ID. IDs that do not match an existing prediction file return HTTP 404. |
Example Request
📊 Response Format
Success Response (Random)
The total_fortunes value is discovered at runtime by counting *.json files in the predictions/ directory — so it grows automatically as you add new fortunes.
Error Response — ID Not Found
When ?id=N points at a missing prediction file, the API returns HTTP 404:
📄 Fortune Object
| Field | Type | Description |
|---|---|---|
id |
integer | 1-based identifier matching the prediction filename |
thai |
string | Thai prediction text |
chinese |
string | Simplified Chinese prediction text |
english |
string | English prediction text |
⚠️ Error Responses
The API has only one error condition: requesting an id that does not exist as a prediction file.
| HTTP Status | error message |
Trigger |
|---|---|---|
| 404 | Fortune file not found |
?id=N for an N that has no matching predictions/N.json |
🔗 Integration Examples
JavaScript/AJAX
PHP
Python
🚦 Rate Limits
This endpoint is rate-limited per client identity (IP address, or API key when one is supplied): 120 requests per minute. When the budget is exhausted the API responds with HTTP 429 and includes X-RateLimit-* headers so clients can self-throttle. The exact policy is configured in api/includes/api_config.php.
🏛️ Cultural Considerations
- Respectful Content: All fortunes are designed to be positive and respectful across cultures
- Cultural Sensitivity: Translations maintain cultural context appropriate for each language
- Entertainment Purpose: This API is designed for entertainment and should not be used for serious life decisions
- Diverse Perspectives: Fortunes cover universal human experiences across different cultures
🎯 Ready to Try?
Test the Fortune Teller API with our interactive web interface or start integrating it into your application.
Try Web Interface Test API Endpoint