nos-private-api is a small Python package for reading NOS app content through the same first-party endpoints used by the Android app. It includes a typed client for article feeds and item details, plus reverse-engineered API notes in docs/apis.

[!IMPORTANT] This project targets an unofficial private API. Endpoints, response shapes, and header requirements can change without notice.

Features

• Generate the app-style X-NOS header automatically.
• Fetch paginated item feeds with category, subcategory, type, and before filters.
• Fetch full article details by item ID.
• Parse item summaries, articles, images, videos, links, tags, and categories into dataclasses.
• Keep the original API payload available on .raw for fields that are not modeled yet.

Installation

Install from the repository root:

python -m pip install .

For local development:

python -m pip install -e .

Usage

List news articles

from nos_private_api import NosClient

client = NosClient()

page = client.list_items(
    main_categories="nieuws",
    types="article",
)

for item in page.items:
    print(item.id, item.title)

Fetch an article

article = client.get_item(page.items[0].id)

print(article.title)
print(article.published_at)
print(article.text)

for image in article.images:
    print(image.description, image.best_url(width=800, ratio="16:9"))

for video in article.videos:
    print(video.title, video.best_url())

for link in article.links:
    print(link.title, link.url)

Filter by subcategory

page = client.list_items(
    main_categories="nieuws",
    sub_categories="politiek",
    types="article",
)

Common news subcategories include binnenland, buitenland, cultuur-en-media, economie, koningshuis, opmerkelijk, politiek, and tech.

Follow pagination

page = client.list_items(main_categories="nieuws")

while page.links.next:
    page = client.list_items(url=page.links.next)

    for item in page.items:
        print(item.id, item.title)

API map

The docs/apis directory documents the Android API research behind the client:

Development

This package uses setuptools and depends on httpx.

python -m pip install -e .
python -c "from nos_private_api import NosClient; print(NosClient.BASE_URL)"