Metadata-Version: 2.4
Name: nos-private-api
Version: 0.1.0
Summary: Python client for the NOS Android app API
Author: 11philip22
License-Expression: MIT
Project-URL: Homepage, https://github.com/11philip22/nos-private-api
Project-URL: Repository, https://github.com/11philip22/nos-private-api
Project-URL: Issues, https://github.com/11philip22/nos-private-api/issues
Keywords: nos,news,api,client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx
Dynamic: license-file

<div align="center">

# nos-private-api

*Python client and notes for the NOS Android app API*

![Python](https://img.shields.io/badge/Python->=3.10-3776ab?style=flat-square&logo=python&logoColor=white)
![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)
![HTTPX](https://img.shields.io/badge/httpx-client-1f6feb?style=flat-square)

[Features](#features) - [Installation](#installation) - [Usage](#usage) - [API map](#api-map)

</div>

`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`](https://github.com/11philip22/nos-private-api/tree/main/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:

```bash
python -m pip install .
```

For local development:

```bash
python -m pip install -e .
```

## Usage

### List news articles

```python
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

```python
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

```python
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

```python
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`](https://github.com/11philip22/nos-private-api/tree/main/docs/apis) directory documents the Android API research behind the client:

| Area | Notes |
| --- | --- |
| [`auth.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/auth.md) | Timestamp endpoint and `X-NOS` header format |
| [`nos-content.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/nos-content.md) | Items, pages, search, live, weather, soccer, and widget endpoints |
| [`recommendations.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/recommendations.md) | Content-based and collaborative recommendation endpoints |
| [`region-and-third-party.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/region-and-third-party.md) | Regional broadcaster APIs and NPO telemetry endpoints |

## Development

This package uses `setuptools` and depends on `httpx`.

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