readly.com APIreadly.com ↗
Search and browse thousands of Readly magazines and newspapers. Get publication metadata, back issues, categories, and cover images via 5 structured endpoints.
curl -X GET 'https://api.parse.bot/scraper/ae3d403e-2278-44aa-8c08-ba47f2724961/list_publications?page=1&limit=3&topic_id=Q38926' \ -H 'X-API-Key: $PARSE_API_KEY'
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 client-side 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 objects with id, issue_id, title, cover, release_date, url_formatted_title, issue_number, publication_name, media_page_id"
},
"sample": {
"data": {
"page": 1,
"limit": 25,
"topic_id": "Q38926",
"total_items": 38,
"publications": [
{
"id": 21561785,
"cover": "https://content.cafeyn.co/Public/Publications/21561785/22590925/Images/Detail.jpg",
"title": "The Guardian",
"issue_id": 22590925,
"issue_number": 20260507,
"release_date": "2026-05-07T05:00:00",
"media_page_id": 923,
"publication_name": "The Guardian",
"url_formatted_title": "the-guardian"
}
]
},
"status": "success"
}
}About the readly.com 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.
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.
- 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 | 250 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.