This repository turns the Reuters Android API mapping work into a minimal Python package. It can read public section pages, follow the mobile "fetch more" pagination flow, and fetch public article details while keeping the original JSON payload available for callers that need fields beyond the typed dataclasses.

[!IMPORTANT] This is an unofficial client for public Reuters web/mobile endpoints observed from the Android app. Endpoints can change, and Reuters may reject or challenge automated traffic. Use it responsibly and respect Reuters' terms.

Features

• Iterate Reuters category and section article summaries from paths such as /world/americas/.
• Optionally follow category pagination through Reuters' fetch_more endpoint.
• Fetch public article detail payloads, including authors, timing metadata, and body content elements.
• Return frozen dataclasses with common fields plus the raw Reuters JSON.
• Include API mapping notes for mobile REST, GraphQL/identity behavior, and the Android widget feed.

Installation

Requires Python 3.9 or newer.

python -m pip install reuters-private-api

For local development, use an editable install:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Quick Start

from itertools import islice

from reuters_private_api import ReutersClient

client = ReutersClient()

summaries = list(islice(client.iter_articles("/world/americas/", load_more=True), 10))

for summary in summaries:
    print(summary.display_time, summary.title)
    print(summary.url)

article = client.get_article(summaries[0].url)
print(article.title)
print(article.read_minutes)

for element in article.content_elements:
    print(element.get("type"), element.get("content"))

[!TIP] Pass Reuters URL paths, not full URLs. Use /world/americas/ or /world/example-2026-08-13/; full https://... URLs are rejected on purpose.

API

ReutersClient(timeout=30, client=None)

Creates an HTTP client configured for Reuters' public JSON endpoints. You can pass your own httpx.Client to control retries, proxies, custom transports, or shared connection pooling.

iter_articles(category_path, load_more=False)

Yields ArticleSummary objects for a Reuters category path.

for article in client.iter_articles("/world/", load_more=True):
    print(article.id, article.title)

When load_more=True, the client follows the Reuters category pagination endpoint until Reuters returns an empty page. Results are de-duplicated by article ID.

get_article(article_path)

Fetches one public article detail payload and returns an Article.

summary = next(client.iter_articles("/business/"))
article = client.get_article(summary.url)

Data Models

API Notes

The detailed mapping is in docs/apis:

• mobile-rest.md covers the public mobile JSON endpoints, category pagination, article detail responses, menu/config routes, markets quotes, and geo helper.
• graphql-identity.md documents the observed GraphQL transport, public search/feed behavior, authenticated-field boundaries, and embedded operation inventory.
• native-widget.md describes the Android widget feed and parsing behavior.

Development

The package is intentionally small: reuters_private_api/client.py contains the HTTP behavior, and reuters_private_api/types.py contains the dataclasses.

Run a quick syntax check with:

python -m compileall reuters_private_api