From 830b61ae438422e9ccd78aa08d4235793814a573 Mon Sep 17 00:00:00 2001 From: SergeantPanda Date: Fri, 24 Apr 2026 15:55:16 -0500 Subject: [PATCH] chore(docs): remove EPG Program Search API documentation. This is well documented with the swagger api now. --- docs/EPG_PROGRAM_SEARCH_API.md | 448 --------------------------------- 1 file changed, 448 deletions(-) delete mode 100644 docs/EPG_PROGRAM_SEARCH_API.md diff --git a/docs/EPG_PROGRAM_SEARCH_API.md b/docs/EPG_PROGRAM_SEARCH_API.md deleted file mode 100644 index 118af9ba..00000000 --- a/docs/EPG_PROGRAM_SEARCH_API.md +++ /dev/null @@ -1,448 +0,0 @@ -# EPG Program Search API - -## Overview - -The EPG Program Search API provides powerful filtering and search capabilities for EPG (Electronic Program Guide) program data. It supports complex text queries with AND/OR operators, parenthetical grouping, regex patterns, time-based filtering, and channel/stream matching. - -**Endpoint:** `GET /api/epg/programs/search/` - -**Authentication:** Required (JWT Bearer token) - ---- - -## Query Parameters - -### Text Search Parameters - -#### **`title`** (string, optional) -Search program titles with support for: -- Simple terms: `title=football` -- AND operator: `title=premier AND league` -- OR operator: `title=Newcastle OR Villa` -- Nested groups with parentheses: `title=(Newcastle OR NEW) AND (Villa OR AST)` -- Default behavior: Space-separated terms use AND - -**Examples:** -``` -title=sports -title=premier AND league -title=Newcastle OR Villa -title=(Newcastle OR NEW) AND (Villa OR AST) -``` - -#### **`title_regex`** (boolean, optional) -When `true`, interprets the `title` parameter as a case-insensitive regex pattern. - -**Examples:** -``` -title=^The&title_regex=true # Programs starting with "The" -title=\d{4}&title_regex=true # Programs with 4-digit years -title=\b(United|City)\b&title_regex=true # Match "United" or "City" as whole words -``` - -#### **`title_whole_words`** (boolean, optional) -When `true`, matches only whole words. Prevents "NEW" from matching "News" or "Newcastle". - -**Examples:** -``` -title=NEW&title_whole_words=true # Matches "NEW" but not "News" or "Newsletter" -``` - -#### **`description`** (string, optional) -Search program descriptions. Supports the same features as `title`: -- AND/OR operators -- Parenthetical grouping -- Works with `description_regex` and `description_whole_words` - -#### **`description_regex`** (boolean, optional) -When `true`, interprets `description` as a case-insensitive regex pattern. - -#### **`description_whole_words`** (boolean, optional) -When `true`, matches only whole words in descriptions. - ---- - -### Time Filtering Parameters - -#### **`airing_at`** (ISO 8601 datetime, optional) -Find programs airing at a specific moment in time. Matches programs where: -``` -start_time <= airing_at < end_time -``` - -**Example:** -``` -airing_at=2026-02-14T20:00:00Z -``` - -#### **`start_after`** (ISO 8601 datetime, optional) -Programs starting at or after this time. - -**Example:** -``` -start_after=2026-02-14T18:00:00Z -``` - -#### **`start_before`** (ISO 8601 datetime, optional) -Programs starting at or before this time. - -#### **`end_after`** (ISO 8601 datetime, optional) -Programs ending at or after this time. - -#### **`end_before`** (ISO 8601 datetime, optional) -Programs ending at or before this time. - -**Combined time range example:** -``` -start_after=2026-02-14T19:00:00Z&start_before=2026-02-14T22:00:00Z -``` - ---- - -### Channel & Stream Filtering - -#### **`channel`** (string, optional) -Filter by channel name (case-insensitive substring match). - -**Example:** -``` -channel=BBC One -``` - -#### **`channel_id`** (integer, optional) -Filter by exact channel ID. - -**Example:** -``` -channel_id=123 -``` - -#### **`stream`** (string, optional) -Filter by stream name (case-insensitive substring match). - -**Example:** -``` -stream=Sky Sports -``` - -#### **`group`** (string, optional) -Filter by channel group name OR stream group name (case-insensitive substring match). - -**Example:** -``` -group=Sports -``` - -#### **`epg_source`** (integer, optional) -Filter by EPG source ID. - -**Example:** -``` -epg_source=5 -``` - ---- - -### Response Customization - -#### **`fields`** (string, optional) -Comma-separated list of fields to include in response. Reduces payload size for specific use cases. - -**Available fields:** -- `id`, `title`, `sub_title`, `description` -- `start_time`, `end_time`, `tvg_id`, `custom_properties` -- `epg_source`, `epg_name`, `epg_icon_url` -- `channels`, `streams` - -**Example:** -``` -fields=title,start_time,end_time,channels -``` - ---- - -### Pagination Parameters - -#### **`page`** (integer, optional, default: 1) -Page number for paginated results. - -#### **`page_size`** (integer, optional, default: 50, max: 500) -Number of results per page. - -**Example:** -``` -page=2&page_size=100 -``` - ---- - -## Response Format - -### Standard Response (with pagination) - -```json -{ - "count": 345, - "next": "http://example.com/api/epg/programs/search/?page=2&...", - "previous": null, - "results": [ - { - "id": 21382804, - "title": "Premier League: Newcastle vs Aston Villa", - "sub_title": "Match Week 25", - "description": "LIVE coverage from St James' Park", - "start_time": "2026-02-14T20:00:00Z", - "end_time": "2026-02-14T22:00:00Z", - "tvg_id": "skysportspremierleague.uk", - "custom_properties": {"category": "Sports"}, - "epg_source": "Sky EPG UK", - "epg_name": "Sky Sports Premier League", - "epg_icon_url": "https://example.com/icon.png", - "channels": [ - { - "id": 14419, - "name": "Sky Sports Premier League", - "channel_number": 401.0, - "channel_group": "UK | Sky Sports", - "tvg_id": "skysportspremierleague.uk" - } - ], - "streams": [ - { - "id": 300, - "name": "Sky Sports PL HD", - "channel_group": "UK | Sports", - "tvg_id": "SkySportsPL.uk", - "m3u_account": "my_provider" - } - ] - } - ] -} -``` - -### With Field Selection - -Request: `?fields=title,start_time,end_time` - -```json -{ - "count": 345, - "next": "...", - "previous": null, - "results": [ - { - "title": "Premier League: Newcastle vs Aston Villa", - "start_time": "2026-02-14T20:00:00Z", - "end_time": "2026-02-14T22:00:00Z" - } - ] -} -``` - ---- - -## Usage Examples - -### Example 1: Find football matches airing now -```bash -curl -H "Authorization: Bearer $TOKEN" \ - "http://localhost:9191/api/epg/programs/search/?title=football&airing_at=2026-02-14T20:00:00Z" -``` - -### Example 2: Complex team search with abbreviations -Find programs mentioning either full names or abbreviations: -```bash -curl -H "Authorization: Bearer $TOKEN" \ - "http://localhost:9191/api/epg/programs/search/?title=(Newcastle%20OR%20NEW)%20AND%20(Villa%20OR%20AST)&airing_at=2026-02-14T20:00:00Z" -``` - -### Example 3: Whole word matching to avoid false positives -```bash -curl -H "Authorization: Bearer $TOKEN" \ - "http://localhost:9191/api/epg/programs/search/?title=NEW&title_whole_words=true&airing_at=2026-02-14T20:00:00Z" -``` -This matches "NEW" but not "News", "Newcastle", or "Newsletter". - -### Example 4: Regex pattern for advanced matching -Find programs starting with "Premier" or "Champions": -```bash -curl -H "Authorization: Bearer $TOKEN" \ - "http://localhost:9191/api/epg/programs/search/?title=^(Premier%7CChampions)&title_regex=true" -``` - -### Example 5: Time window search on specific channel -```bash -curl -H "Authorization: Bearer $TOKEN" \ - "http://localhost:9191/api/epg/programs/search/?channel=BBC%20One&start_after=2026-02-14T18:00:00Z&start_before=2026-02-14T23:00:00Z" -``` - -### Example 6: Minimal response with field selection -```bash -curl -H "Authorization: Bearer $TOKEN" \ - "http://localhost:9191/api/epg/programs/search/?title=sports&fields=title,start_time,end_time&page_size=10" -``` - -### Example 7: Find programs by stream group -```bash -curl -H "Authorization: Bearer $TOKEN" \ - "http://localhost:9191/api/epg/programs/search/?group=Sports&airing_at=2026-02-14T20:00:00Z" -``` - -### Example 8: Find all news programs in next 2 hours -```bash -curl -H "Authorization: Bearer $TOKEN" \ - "http://localhost:9191/api/epg/programs/search/?title=news&start_after=2026-02-14T20:00:00Z&start_before=2026-02-14T22:00:00Z" -``` - ---- - -## Text Query Syntax - -### Operators - -- **AND**: Both terms must be present - - Example: `premier AND league` - -- **OR**: Either term must be present - - Example: `Newcastle OR Villa` - -- **Parentheses**: Group operations for complex logic - - Example: `(A OR B) AND (C OR D)` - -### Operator Precedence - -Left-to-right evaluation with parentheses for grouping: -``` -A AND B OR C → Evaluated as: (A AND B) OR C -(A OR B) AND C → A or B must match, AND C must match -A AND (B OR C) → A must match, AND either B or C must match -``` - -### Default Behavior - -Space-separated terms without explicit operators default to AND: -``` -football premier league → football AND premier AND league -``` - ---- - -## Performance Considerations - -1. **Text searches** use database `LIKE` queries (or regex). For large datasets, consider: - - Using more specific search terms - - Combining with time filters to reduce result set - - Using field selection to reduce response size - -2. **Pagination**: Default page size is 50, max is 500. For large result sets, use pagination rather than increasing page_size to max. - -3. **Regex searches** are more expensive than standard text searches. Use only when necessary. - -4. **Prefetching**: The endpoint automatically prefetches related channels, streams, and groups to avoid N+1 queries. - -5. **Indexes**: The following fields are indexed for fast queries: - - `ProgramData.start_time`, `end_time` - - `EPGData.tvg_id` - - `Channel.channel_number` - ---- - -## Error Handling - -### Authentication Required -```json -{ - "detail": "Authentication credentials were not provided." -} -``` -**Status:** 401 Unauthorized - -### Invalid datetime format -Invalid ISO 8601 datetime values are silently ignored (filter not applied). - -### Invalid regex pattern -If `title_regex=true` and pattern is invalid, the query may fail at the database level. Ensure regex patterns are valid. - ---- - -## Integration Notes - -### Frontend Integration - -```javascript -// Example using fetch API -async function searchPrograms(query) { - const token = localStorage.getItem('accessToken'); - const params = new URLSearchParams(query); - - const response = await fetch( - `/api/epg/programs/search/?${params}`, - { - headers: { - 'Authorization': `Bearer ${token}`, - 'Accept': 'application/json' - } - } - ); - - return await response.json(); -} - -// Usage -const results = await searchPrograms({ - title: '(Newcastle OR NEW) AND (Villa OR AST)', - airing_at: new Date().toISOString(), - page_size: 20 -}); -``` - -### Automation & Scripts - -```python -import requests -from datetime import datetime - -# Get token -response = requests.post('http://localhost:9191/api/accounts/token/', - json={'username': 'user', 'password': 'pass'}) -token = response.json()['access'] - -# Search programs -headers = {'Authorization': f'Bearer {token}'} -params = { - 'title': 'football', - 'airing_at': datetime.utcnow().isoformat() + 'Z', - 'page_size': 50 -} - -response = requests.get( - 'http://localhost:9191/api/epg/programs/search/', - headers=headers, - params=params -) - -programs = response.json() -print(f"Found {programs['count']} matching programs") -``` - ---- - -## API Versioning - -This endpoint was introduced in **version 1.0** and follows semantic versioning. Breaking changes will be announced with major version increments. - ---- - -## Related Endpoints - -- `GET /api/epg/grid/` - Get EPG grid view (24-hour window) -- `POST /api/epg/current-programs/` - Get currently airing programs for specific channels -- `GET /api/epg/programs/` - List all programs (CRUD endpoint) -- `GET /api/epg/sources/` - Manage EPG sources - ---- - -## Support & Feedback - -For issues, feature requests, or questions about this API, please file an issue on the GitHub repository or consult the project documentation.