# RadioMV API

> API documentation for RadioMV Christian radio stations. Provides station configuration, stream URLs, and program schedules.

## Base URL

https://api.radiomv.studio

## Endpoints

### App Configuration
- GET /appv1.json - App config for v1 apps (legacy schedule URLs)
- GET /appv2.json - App config for v2 apps (new schedule schema)

### Program Schedules (v2 - new schema)
- GET /english-programv2.json - English station schedule
- GET /slavic-programv2.json - Slavic station schedule
- GET /spanish-programv2.json - Spanish station schedule (coming soon)
- GET /german-programv2.json - German station schedule (coming soon)

## Documentation

- /index.html - API overview and quick start
- /docs/app.html - App configuration schema reference
- /docs/schedule.html - Schedule schema reference
- /docs/guidelines.html - Integration best practices

## Quick Reference

### Station IDs
- 1: English
- 4: Spanish
- 7: German
- 10: Slavic (Russian)

### Schedule Format
- Days: Numbers 0-6 (0=Sunday, 6=Saturday)
- Times: 24-hour format "HH:MM"
- Timezone: America/Los_Angeles

### Categories
bible-reading, bible-study, sermon, testimony, music, children, family, live, missionary, educational, audiobook, devotional, talk-show

## Example Usage

IMPORTANT: Never hardcode schedule URLs. Always fetch from appv2.json first.

```javascript
// 1. Fetch app config (only hardcode this URL)
const config = await fetch('https://api.radiomv.studio/appv2.json');
const data = await config.json();

// 2. Get schedule URL from station object (don't hardcode!)
const station = data.stations.find(s => s.id === "1");
const scheduleUrl = station.stationScheduleUrl;

// 3. Fetch schedule using URL from config
const schedule = await fetch(scheduleUrl);
const programs = (await schedule.json()).schedule;

// 4. Get today's programs
const today = new Date().getDay();
const todayPrograms = programs.filter(p => p.days.includes(today));
```

## Versioning Strategy
- appv1.json → for legacy apps, points to old schedule URLs
- appv2.json → for new apps, points to v2 schedule URLs
- Schedule files v2: schemaVersion "2.0.0" with new schema (numeric days, 24hr time, categories)

## Notes
- No authentication required
- No rate limiting
- Cache schedule files for 7 days (rarely change)
- Cache app config for 24 hours
- All times in America/Los_Angeles timezone
- IMPORTANT: Only hardcode appv2.json URL - get all other URLs from it