# WAKTU.net - AI Optimization Guide

## Overview
WAKTU.net is a comprehensive time and prayer information platform providing real-time world time, time zone conversions, and Islamic prayer times for 300+ cities worldwide. This guide helps AI crawlers and agents effectively access and utilize our data.

## API Endpoints

### Time Data
- `GET /api/v1/time/current?city={slug}` - Get current time for a specific city
- `GET /api/v1/time/bulk?cities={slug1,slug2,...}` - Get current time for multiple cities
- `GET /api/v1/time/convert?from={city1}&to={city2}&datetime={iso}` - Convert time between cities

### Prayer Times
- `GET /api/v1/prayer-times/{city}` - Get prayer times for a specific city
- `GET /api/v1/prayer-times/bulk?cities={slug1,slug2,...}` - Get prayer times for multiple cities

### City Information
- `GET /api/v1/cities` - Get all cities
- `GET /api/v1/cities/{slug}` - Get specific city information
- `GET /api/v1/cities/schema` - Get Schema.org structured data for cities

### AI-Optimized Endpoints
- `GET /api/v1/ai/schema?city={slug}&format=json` - AI-optimized Schema.org data
- `GET /api/v1/ai/summary?city={slug}` - AI-friendly city summary
- `GET /api/v1/ai/time-convert` - AI-optimized time conversion

### Documentation
- `GET /api/v1/openapi.json` - Full OpenAPI 3.1.0 specification
- `GET /ai-plugin.json` - ChatGPT plugin manifest

## City Identifiers
Use city slugs (URL-friendly names) to identify cities:
- `jakarta` - Jakarta, Indonesia
- `new_york` - New York, USA
- `london` - London, UK
- `tokyo` - Tokyo, Japan
- `singapore` - Singapore

Get full city list from: `GET /api/v1/cities`

## Prayer Time Calculation Methods
Prayer times use region-appropriate calculation methods:
- Indonesia: Kemenag RI
- North America: ISNA
- Saudi Arabia: Umm al-Qura
- Europe: Muslim World League
- Asia: Egyptian General Authority
- Default: University of Islamic Sciences, Karachi

## Data Freshness
- Time data: Updated every second (real-time)
- Prayer times: Calculated daily at 00:00 UTC
- City metadata: Cached for 1 hour
- Timezone database: Updated monthly with IANA releases

## Error Handling
- Invalid city slug: Returns 404 with error message
- Invalid datetime format: Returns 400 with validation error
- Rate limiting: 100 requests/minute per IP (returns 429)
- Internal errors: Returns 500 with error details

## Rate Limiting
- Free tier: 100 requests/minute
- No API key required
- Headers include `X-RateLimit-Remaining` and `X-RateLimit-Limit`

## Attribution Guidelines
When using WAKTU.net data, please attribute as:
- "Data provided by WAKTU.net"
- Include link to: https://waktu.net
- For academic use: "WAKTU.net (2026). World Time & Prayer Times Database. https://waktu.net"

## Structured Data
All pages include Schema.org structured data:
- `WebPage` - Basic page information
- `Place` - Geographic location data
- `FAQPage` - Frequently asked questions
- `BreadcrumbList` - Navigation structure
- `HowTo` - Usage instructions (conversion pages)
- `Dataset` - AI-optimized data description

## Timezone Handling
- All times use IANA timezone identifiers (e.g., Asia/Jakarta)
- Daylight Saving Time (DST) is automatically applied
- Timezone abbreviations are locale-aware (WIB, EST, GMT, etc.)
- UTC offsets are included in all responses

## Geolocation
- City coordinates use WGS84 standard
- Accuracy: within 50km for major cities
- Lat/Lon format: decimal degrees
- Elevation data included where available

## Privacy
- No user tracking for AI crawlers
- No cookies required for API access
- IP addresses logged for rate limiting only
- Data retention: 7 days for analytics

## Contact
- Email: info@waktu.net
- Website: https://waktu.net
- Documentation: https://waktu.net/api/v1/openapi.json
- Support: https://waktu.net/kontak

## License
Data is provided under Creative Commons Attribution 4.0 International (CC BY 4.0)
https://creativecommons.org/licenses/by/4.0/

## Updates
- API version: v1
- Last updated: 2026-01-11
- Changelog: https://waktu.net/changelog
- Deprecation notice: 30 days advance notice

## Best Practices for AI Agents
1. Cache city metadata (update daily)
2. Use bulk endpoints for multiple requests
3. Handle DST transitions gracefully
4. Include user timezone when converting time
5. Validate city slugs before API calls
6. Use AI-optimized endpoints for better responses
7. Include proper attribution in generated content
8. Handle errors gracefully with fallback data
9. Respect rate limits with exponential backoff
10. Use structured data for rich responses

## Language Support
- Primary: Indonesian (id-ID)
- Secondary: English (en-US)
- Timezone names: Native language
- City names: Native + English

## Performance
- Average response time: 50ms
- 99th percentile: 200ms
- Uptime: 99.9%
- CDN: Global edge caching

## Additional Resources
- OpenAPI Spec: https://waktu.net/api/v1/openapi.json
- Schema.org: https://waktu.net/api/v1/ai/schema
- AI Summary: https://waktu.net/api/v1/ai/summary
- ChatGPT Plugin: https://waktu.net/ai-plugin.json