# Xtream Codes API Documentation

Comprehensive API documentation for Xtream Codes IPTV Panel v2.9.2

## Base URL

```
http://SERVER:PORT/
```

Replace `SERVER:PORT` with your IPTV provider's server address and port (e.g., `http://example.com:8080`)

---

## Authentication

All API endpoints require authentication via `username` and `password` query parameters.

### Player API Endpoints

| Endpoint | Description |
|----------|-------------|
| `/player_api.php` | Main player API for retrieving streams, categories, and EPG |
| `/panel_api.php` | Panel API for administrative functions |
| `/api.php` | General API for system functions |

---

## API Endpoints Reference

### 1. Authentication / Account Info

Retrieves user account information and server details.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required) - Your username
- `password` (required) - Your password

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD"
```

**Example Response:**
```json
{
  "user_info": {
    "username": "11111111",
    "password": "22222222",
    "message": "Welcome back",
    "auth": 1,
    "status": "Active",
    "exp_date": "1558621852",
    "is_trial": "0",
    "active_cons": "0",
    "created_at": "1542987052",
    "max_connections": "2",
    "allowed_output_formats": ["m3u8", "ts", "rtmp"]
  },
  "server_info": {
    "url": "111.222.333.444",
    "port": "8080",
    "https_port": "8443",
    "server_protocol": "http",
    "rtmp_port": "25462",
    "timezone": "Europe/London",
    "timestamp_now": 1545170300,
    "time_now": "2024-12-18 21:58:20"
  }
}
```

---

### 2. Live TV Categories

Get all live TV stream categories.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_live_categories`

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_live_categories"
```

**Example Response:**
```json
[
  {
    "category_id": "1",
    "category_name": "News",
    "parent_id": 0
  },
  {
    "category_id": "2",
    "category_name": "Sports",
    "parent_id": 0
  }
]
```

---

### 3. VOD (Movies) Categories

Get all VOD/movie categories.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_vod_categories`

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_vod_categories"
```

---

### 4. Series Categories

Get all TV series categories.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_series_categories`

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_series_categories"
```

---

### 5. Live Streams

Get all live TV streams.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_live_streams`
- `category_id` (optional) - Filter by category ID

**Example Request:**
```bash
# All live streams
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_live_streams"

# Live streams by category
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_live_streams&category_id=1"
```

**Example Response:**
```json
[
  {
    "num": 1,
    "name": "BBC News",
    "stream_type": "live",
    "stream_id": "1001",
    "stream_icon": "http://SERVER:PORT/images/bbc_news.png",
    "epg_channel_id": "bbc.news",
    "added": "1542987052",
    "category_id": "1",
    "custom_sid": "",
    "tv_archive": 0,
    "direct_source": "",
    "tv_archive_duration": 0
  }
]
```

---

### 6. VOD Streams (Movies)

Get all VOD/movie streams.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_vod_streams`
- `category_id` (optional) - Filter by category ID

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_vod_streams"
```

**Example Response:**
```json
[
  {
    "num": 1,
    "name": "Movie Title",
    "stream_type": "movie",
    "stream_id": "5001",
    "stream_icon": "http://SERVER:PORT/images/movie.jpg",
    "rating": "7.5",
    "rating_imdb": "7.5",
    "added": "1542987052",
    "category_id": "10",
    "container_extension": "mp4",
    "custom_sid": "",
    "direct_source": ""
  }
]
```

---

### 7. Series

Get all TV series.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_series`
- `category_id` (optional) - Filter by category ID

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_series"
```

**Example Response:**
```json
[
  {
    "num": 1,
    "name": "Breaking Bad",
    "series_id": "2001",
    "cover": "http://SERVER:PORT/images/breaking_bad.jpg",
    "plot": "A high school chemistry teacher...",
    "cast": "Bryan Cranston, Aaron Paul",
    "rating": "9.5",
    "director": "Vince Gilligan",
    "genre": "Drama, Crime",
    "releaseDate": "2008-01-20",
    "last_modified": "1542987052",
    "category_id": "20"
  }
]
```

---

### 8. Series Info (Episodes)

Get detailed information about a TV series including all seasons and episodes.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_series_info`
- `series_id` (required) - The series ID

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_series_info&series_id=2001"
```

**Example Response:**
```json
{
  "seasons": [
    {
      "air_date": "2008-01-20",
      "episode_count": 7,
      "id": 3572,
      "name": "Season 1",
      "overview": "...",
      "season_number": 1,
      "cover": "...",
      "cover_big": "..."
    }
  ],
  "info": {
    "name": "Breaking Bad",
    "cover": "...",
    "plot": "...",
    "cast": "...",
    "director": "...",
    "genre": "...",
    "releaseDate": "...",
    "last_modified": "...",
    "rating": "..."
  },
  "episodes": {
    "1": [
      {
        "id": "3001",
        "episode_num": 1,
        "title": "Pilot",
        "container_extension": "mp4",
        "info": {
          "duration": "3600",
          "movie_image": "..."
        }
      }
    ]
  }
}
```

---

### 9. VOD Info

Get detailed information about a VOD/movie.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_vod_info`
- `vod_id` (required) - The VOD stream ID

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_vod_info&vod_id=5001"
```

**Example Response:**
```json
{
  "info": {
    "name": "Movie Title",
    "cover": "http://SERVER:PORT/images/movie.jpg",
    "plot": "Movie description...",
    "cast": "Actor 1, Actor 2",
    "director": "Director Name",
    "genre": "Action",
    "releaseDate": "2023-01-01",
    "rating": "7.5",
    "duration": "7200",
    "video": {
      "index": 0,
      "codec_name": "h264",
      "width": 1920,
      "height": 1080
    }
  },
  "movie_data": {
    "stream_id": "5001",
    "name": "Movie Title",
    "added": "1542987052",
    "category_id": "10",
    "container_extension": "mp4"
  }
}
```

---

### 10. Short EPG (Electronic Program Guide)

Get upcoming EPG for a live stream (next few programs).

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_short_epg`
- `stream_id` (required) - The live stream ID
- `limit` (optional) - Number of EPG entries (default: 10)

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_short_epg&stream_id=1001&limit=5"
```

**Example Response:**
```json
{
  "epg_listings": [
    {
      "id": "1",
      "epg_id": "1",
      "title": "News at 6",
      "lang": "en",
      "start": "2024-12-18 18:00:00",
      "end": "2024-12-18 19:00:00",
      "description": "Evening news broadcast",
      "channel_id": "bbc.news"
    }
  ]
}
```

---

### 11. Full EPG for Stream

Get all EPG listings for a specific live stream.

**Endpoint:** `GET /player_api.php`

**Parameters:**
- `username` (required)
- `password` (required)
- `action` (required) = `get_simple_data_table`
- `stream_id` (required) - The live stream ID

**Example Request:**
```bash
curl "http://SERVER:PORT/player_api.php?username=YOUR_USERNAME&password=YOUR_PASSWORD&action=get_simple_data_table&stream_id=1001"
```

---

## Streaming URLs

### Live Stream URL Format

```
http://SERVER:PORT/live/USERNAME/PASSWORD/STREAM_ID.TS
http://SERVER:PORT/live/USERNAME/PASSWORD/STREAM_ID.m3u8
```

**Example:**
```
http://SERVER:PORT/live/user/pass/1001.ts
http://SERVER:PORT/live/user/pass/1001.m3u8
```

### VOD/Movie URL Format

```
http://SERVER:PORT/movie/USERNAME/PASSWORD/STREAM_ID.EXTENSION
```

**Example:**
```
http://SERVER:PORT/movie/user/pass/5001.mp4
```

### Series Episode URL Format

```
http://SERVER:PORT/series/USERNAME/PASSWORD/STREAM_ID.EXTENSION
```

**Example:**
```
http://SERVER:PORT/series/user/pass/3001.mp4
```

---

## M3U Playlist URL

Get complete M3U playlist for all channels:

```
http://SERVER:PORT/get.php?username=USERNAME&password=PASSWORD&type=m3u_plus&output=ts
```

Parameters:
- `type` = `m3u` or `m3u_plus` (m3u_plus includes EPG)
- `output` = `ts` or `m3u8`

---

## EPG (XMLTV) URL

Get EPG data in XMLTV format:

```
http://SERVER:PORT/xmltv.php?username=USERNAME&password=PASSWORD
```

---

## Error Responses

### Authentication Failed
```json
{
  "user_info": {
    "auth": 0,
    "status": "Invalid",
    "message": "Invalid username/password"
  }
}
```

### Expired Account
```json
{
  "user_info": {
    "auth": 0,
    "status": "Expired",
    "message": "Account expired"
  }
}
```

### Max Connections Reached
```json
{
  "user_info": {
    "auth": 0,
    "status": "Max connections reached",
    "message": "Too many connections"
  }
}
```

---

## Code Examples

### JavaScript/Axios
```javascript
const getLiveStreams = async (server, username, password) => {
  const response = await axios.get(
    `${server}/player_api.php`,
    {
      params: {
        username,
        password,
        action: 'get_live_streams'
      }
    }
  );
  return response.data;
};
```

### PHP
```php
<?php
$server = 'http://SERVER:PORT';
$username = 'YOUR_USERNAME';
$password = 'YOUR_PASSWORD';

// Get live streams
$url = "{$server}/player_api.php?username={$username}&password={$password}&action=get_live_streams";
$response = file_get_contents($url);
$streams = json_decode($response, true);

print_r($streams);
?>
```

### Python
```python
import requests

def get_live_streams(server, username, password):
    url = f"{server}/player_api.php"
    params = {
        'username': username,
        'password': password,
        'action': 'get_live_streams'
    }
    response = requests.get(url, params=params)
    return response.json()

# Usage
streams = get_live_streams('http://SERVER:PORT', 'USERNAME', 'PASSWORD')
print(streams)
```

---

## Rate Limiting & Best Practices

1. **Cache responses** - Don't make API calls on every request
2. **Respect rate limits** - Don't hammer the server with requests
3. **Store credentials securely** - Never expose credentials in client-side code
4. **Use HTTPS when available** - Secure your connection
5. **Handle errors gracefully** - Check auth status before processing

---

## Postman Collection

A complete Postman collection is available in `XTREAM_CODES_API.postman_collection.json`

Import the collection and set these environment variables:
- `server` - Your server URL (e.g., `http://example.com:8080`)
- `username` - Your username
- `password` - Your password

---

## Support & Resources

- GitHub: https://github.com/worldofiptvcom/xtream-codes-api-documentation
- Python Library: https://github.com/chazlarson/py-xtream-codes
- Xtream UI: https://xtream-ui.org/

---

*Document Version: 1.0*
*Last Updated: January 2025*