ilpost-api-wrapper

A Python wrapper for the Il Post public search API. Searches articles, podcast episodes, and newsletters — no authentication required.

Installation

pip install ilpost-api-wrapper

Requires Python 3.9+. No third-party dependencies.

Quick start

from ilpost import IlPostClient, SortOrder, ContentType, DateRange

client = IlPostClient()

result = client.search("berlusconi")
for doc in result.docs:
    print(doc.title, doc.link)

API reference

IlPostClient(timeout=10)

Common parameters

fetch_content is available on search(), search_articles(), paginate(), and get_by_date(). It has no effect on podcast or newsletter results — doc.content will be None for those types.

get_by_date(date, *, fetch_content=False)

Returns all articles published on date by scraping the Il Post date-archive page (https://www.ilpost.it/YYYY/MM/DD/), paginating through all pages automatically. Each article is then enriched with API fields (id, tags, category, subscriber status, full timestamp) via a title-based search lookup (with a summary-keyword fallback). Articles that cannot be matched in the search index are excluded from the results.

The following recurring article types are automatically skipped before enrichment, as they are not available in the search API: post-it external-link articles (pre-2017), Peanuts comic strips, daily photo roundups, newspaper front-page galleries (le-prime-pagine-*), and meteo forecast articles.

Raises ValueError if date is in the future or within the last 5 days (the search index has a ~5 day lag; recent dates cannot be enriched).

Enums

SortOrder

ContentType

DateRange

SearchResult

Document

Examples

from ilpost import IlPostClient, SortOrder, ContentType, DateRange

client = IlPostClient()

# Most recent articles in politics
result = client.search_articles(
    "renzi",
    sort=SortOrder.NEWEST,
    category="politica",
    date_range=DateRange.PAST_30_DAYS,
)

# Podcast search
result = client.search_podcasts("cacao", sort=SortOrder.NEWEST)

# Paginate through all results, 5 per page
for page in client.paginate("sicilia", hits=5, max_pages=10):
    print(f"Page {page.page}/{page.total_pages}")
    for doc in page.docs:
        print(f"  [{doc.type}] {doc.title}")

# Access filter counts from a response
result = client.search("europa")
for group in result.filters:
    print(f"{group.label}:")
    for opt in group.options:
        print(f"  {opt.label}: {opt.doc_count}")

# Fetch full article text alongside search results
result = client.search_articles("economia", hits=5, fetch_content=True)
for doc in result.docs:
    print(doc.title)
    if doc.content:
        print(doc.content[:300])

# Use the scraper directly (e.g. for parallel fetching)
from ilpost import fetch_article_content
text = fetch_article_content("https://www.ilpost.it/2026/04/02/...")

# Fetch all articles published on a specific date
import datetime
docs = client.get_by_date(datetime.date(2025, 11, 12))
for doc in docs:
    print(doc.title, doc.timestamp)

CLI

The ilpost-search command is included with the package:

usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
                     [--sort {relevance,newest,oldest}]
                     [--date {all,year,month}] [--category CATEGORY [CATEGORY ...]]
                     [--page PAGE] [--hits HITS] [--all-pages] [--max-pages N]
                     [--fetch-content] [--output-json] [--output-dir DIR]
                     [--archive-date YYYY-MM-DD]
                     [query]

Each result is printed with labelled fields: type, category, tags, title, link, date, score, summary, and either content (when --fetch-content is used) or excerpt (search highlight).

--output-json suppresses stdout and writes results to a JSON file instead. The filename is generated automatically from the timestamp and query (e.g. 20260411_143000_matteo_zuppi.json). Use --output-dir to specify a target directory (defaults to the current working directory). The file path is printed to stdout so it can be captured by scripts.

# Basic search
ilpost-search berlusconi

# Most recent articles in politics
ilpost-search renzi --type articles --sort newest --category politica

# Podcast search, past 30 days
ilpost-search cacao --type podcasts --date month

# Page 2, 5 results per page, oldest first
ilpost-search sicilia --sort oldest --hits 5 --page 2

# Fetch all pages of newsletter results (up to 3 pages)
ilpost-search economia --type newsletters --all-pages --max-pages 3

# Fetch full article text for each result
ilpost-search bondi --type articles --hits 3 --fetch-content

# Filter by multiple categories (OR union)
ilpost-search cultivar --category scienza italia mondo

# Save results to a JSON file in the current directory
ilpost-search berlusconi --hits 20 --output-json

# Save results to a specific directory
ilpost-search berlusconi --all-pages --output-json --output-dir ~/Desktop

# Fetch all articles published on a specific date
ilpost-search --archive-date 2025-11-12

# Fetch articles by date and save to JSON
ilpost-search --archive-date 2025-11-12 --output-json

# Fetch articles by date with full content
ilpost-search --archive-date 2025-11-12 --fetch-content

Notes

• Paywalled content (subscriber: true) is included in search results — title, summary, and highlight are visible, but the full article requires an active ilpost.it subscription.
• When sorting by date (NEWEST or OLDEST), score is always 0.0.
• The category filter only applies to articles. It is ignored by the server when content_type=PODCASTS.
• Timestamps are in Italian local time (CET/CEST) with no UTC offset.
• The search index has a ~5 day lag. Articles published in the last few days will not appear in search results.