TV Channels by Country 🌍

A community-maintained JSON list of TV station names and categories from around the world — free to use in any project that needs structured channel data.

Whether you're building an IPTV app, a channel lookup tool, or anything else, you're welcome here.

Table of contents

• Install
• Usage
• API
• Data format
• Contributing
• License

Install

npm install @edenware/tv-channels-by-country

Usage

// ESM
import { getChannels, listCountries, search, generate } from '@edenware/tv-channels-by-country';

// CJS
const { getChannels, listCountries, search, generate } = require('@edenware/tv-channels-by-country');

// Channels by country (loads only the requested country, cached)
const br = await getChannels('br');
// { "Religious": [{ name, keywords, ... }], "News": [...], ... }

// List all available country codes
const countries = await listCountries();

// Search by keywords
const matches = await search('globo', { countries: ['br'], limit: 18 });
// [{ name, keywords, country, category, ... }, ...]

// Generate a list from multiple countries by priority
const list = await generate({ countries: ['br', 'us'], limit: 256, minPerCategory: 18 });
// [{ name, keywords, country, category, ... }, ...]

TypeScript: types are included. Dual format: ESM and CommonJS. Direct JSON: import br from '@edenware/tv-channels-by-country/channels/br.json' (with bundler).

API

getChannels(countryCode)

Returns channels grouped by category for a country. Uses ISO 3166-1 alpha-2 (e.g. 'br', 'us'). Case-insensitive. Returns null if country not found.

listCountries()

Returns a sorted array of available country codes.

search(keywords, options?)

Searches channels by keywords across countries and categories.

| Option | Type | Default | Description | |---------------|----------|---------|--------------------------------------| | countries | string[] | all | Filter by country codes | | categories | string[] | all | Filter by category names | | retransmits | string | 'all' | 'parents' | 'affiliates' | 'all' | | limit | number | 100 | Max results |

generate(options)

Builds a list of channels from multiple countries, sorted by priority, with balanced categories.

| Option | Type | Default | Description | |--------------------|----------|---------|-----------------------------------------------------| | countries | string[] | required| Country codes to merge | | categories | string[] | all | Filter by category | | retransmits | string | 'all' | 'parents' | 'affiliates' | 'all' | | limit | number | 256 | Max results | | minPerCategory | number | 18 | Target channels per category | | mainCountryFull | boolean | false | If true, include ALL channels from first country | | freeOnly | boolean | false | If true, includes only free-to-air channels (isFree: true) |

Data format (channels/)

Files: channels/{country}.json. Each file maps category name → array of channel objects.

| Field | Type | Description | |----------------|-----------------|-------------| | name | string | Display name (required) | | keywords | string | Search terms for M3U lookup. Use -x for excludes; \| for OR. | | retransmits | string | null | Affiliate: parent network rebroadcast | | shortName | string | null | Acronym or short name | | isFree | boolean | Free-to-air | | logo | string | null | Logo URL | | website | string | null | Official site | | priority | number | 0–10, relative to country+category. Default 5. |

Compact format: Omit keywords when derived from name, logo/website/retransmits when null, priority when 5.

See channels/README.md for full schema.

Contributing

Contributions are welcome.

• Fix typos
• Add missing channels for your country
• Improve keywords for better matching
• Open issues for suggestions or bugs

See CONTRIBUTING.md for guidelines.

License

MIT © Efox