Readly APIreadly.com ↗
Search and browse thousands of Readly magazines and newspapers. Get publication metadata, back issues, categories, and cover images via 5 structured endpoints.
What is the Readly API?
The Readly API exposes 5 endpoints for querying the Readly magazine and newspaper catalogue. Use list_publications to browse the latest or category-filtered titles, search_publications to find publications by keyword, and get_publication_details to retrieve editorial descriptions, release frequency, and total back-issue counts for any publication in the Readly catalogue.
curl -X GET 'https://api.parse.bot/scraper/ae3d403e-2278-44aa-8c08-ba47f2724961/list_publications?page=1&limit=25&topic_id=Q38926' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace readly-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Readly SDK walkthrough — browse categories, search publications, fetch details and issues."""
from parse_apis.readly_api import Readly, PublicationNotFound
client = Readly()
# List all magazine categories
for cat in client.categories.list(limit=5):
print(cat.name, cat.id, len(cat.sub_topics))
# Search for publications by keyword
summary = client.publicationsummaries.search(query="Forbes", limit=1).first()
if summary:
print(summary.title, summary.id, summary.release_date)
# Drill into full details from a summary
detail = summary.details()
print(detail.title, detail.release_frequency, detail.total_issues)
# List back issues for this publication
for issue in summary.issues.list(limit=3):
print(issue.title, issue.release_date, issue.page_count)
# Browse publications in a specific topic
for pub in client.publicationsummaries.list(topic_id="Q38926", limit=3):
print(pub.title, pub.publication_name, pub.issue_number)
# Typed error handling: fetch a non-existent publication
try:
client.publications.get(id="99999999")
except PublicationNotFound as exc:
print(f"Not found: {exc.publication_id}")
print("exercised: categories.list / publicationsummaries.search / details / issues.list / publicationsummaries.list / publications.get")List publications from the Readly catalogue. Without a topic_id, returns the latest/hot publications. With a topic_id (from list_categories), returns publications in that category. Results are paginated by page number; each page returns up to `limit` items from the full topic listing.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| limit | integer | Number of items per page. |
| topic_id | string | Topic/category ID from list_categories (e.g. 'Q38926' for News & Politics). Omitting returns the latest/hot publications. |
{
"type": "object",
"fields": {
"page": "integer, current page number",
"limit": "integer, items per page",
"topic_id": "string or null, the topic filter applied",
"total_items": "integer, total items available in this topic",
"publications": "array of publication summary objects with id, issue_id, title, cover, release_date, url_formatted_title, issue_number, publication_name, media_page_id"
}
}About the Readly API
Catalogue Browsing and Search
The list_publications endpoint returns paginated publication objects, each containing id, issue_id, title, cover, release_date, url_formatted_title, issue_number, and publication_name. Without a topic_id it returns the latest or trending titles. Pass a topic_id from list_categories — for example Q38926 for News & Politics — to filter results to a specific category. Both page and limit parameters control pagination.
The search_publications endpoint accepts a query string and returns matching publications with their latest issue information, including cover and release_date. The response includes a total_count field so you can surface how many matching titles exist across the full catalogue.
Publication Details and Back Issues
get_publication_details returns structured metadata for a single publication: title, description, logo_url, release_frequency (e.g. Weekly, Bimonthly), total_issues, publisher_id, and a url_formatted_title slug. This is the endpoint to use when building a publication profile page or filtering a catalogue by release cadence.
get_publication_issues fetches paginated back issues for a given publication_id. Each issue object includes issue_id, title, cover, release_date, issue_number, publication_id, and page_count. The total_count field shows how many issues are archived for that publication. Categories themselves — including nested sub_topics with their own id, name, and color — are available from list_categories, which requires no parameters.
The Readly API is a managed, monitored endpoint for readly.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when readly.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official readly.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a magazine discovery app that lets users browse Readly titles filtered by category using
list_categoriesandlist_publications. - Power a publication search feature that returns cover images and latest issue dates via
search_publications. - Display a full back-issue archive for any magazine using
get_publication_issueswithpage_countfor each issue. - Show a publication profile card with editorial description and release frequency pulled from
get_publication_details. - Create a content calendar tool that tracks release dates across multiple publications using issue
release_datefields. - Build a category browser mapping colour-coded topics and sub-topics from the
list_categoriesresponse to a navigation UI.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Readly have an official developer API?+
What does `get_publication_issues` return, and how far back do back issues go?+
publication_id, each with issue_id, cover, release_date, issue_number, and page_count. The total_count field tells you how many issues are archived. The number of available back issues varies by publication — use get_publication_details to see the total_issues count before paginating through the archive.Can I filter publications by country or language?+
list_publications and search_publications endpoints filter by keyword or topic_id only; there are no language or country parameters in the current spec. You can fork this API on Parse and revise it to add a language or region filter endpoint.Does the API return full article text or issue page content?+
How does category nesting work in `list_categories`?+
categories array includes an id, name, color, and a sub_topics array. Sub-topics carry the same fields. To filter publications by a sub-topic, pass its id as the topic_id parameter in list_publications just as you would a top-level category ID.