Voanews APIvoanews.com ↗
Access VOA Learning English lessons, transcripts, vocabulary, and programs across all proficiency levels via 5 structured API endpoints.
What is the Voanews API?
The VOA Learning English API provides 5 endpoints for accessing English-language lessons, transcripts, vocabulary items, and program listings from learningenglish.voanews.com. The get_lesson_detail endpoint returns full article content including parsed transcript paragraphs, vocabulary definitions, and direct media file URLs (mp3, mp4). You can browse content by program category, run keyword searches with pagination, or fetch featured homepage items — all returning structured JSON.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/1d5dd0c9-3ccf-4b0a-81eb-4c9d1da9977d/get_homepage_featured' \ -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 voanews-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.
from parse_apis.voa_learning_english_api import VOA, Program, LessonSummary, Lesson, FeaturedItem
voa = VOA()
# Browse featured homepage content
for item in voa.featureditems.list():
print(item.title, item.type, item.status)
# Search for lessons about grammar
for lesson in voa.lessonsummaries.search(query="grammar"):
print(lesson.title, lesson.date, lesson.url)
# Get articles for a specific program using the Program enum
for lesson in voa.lessonsummaries.by_program(program=Program.EVERYDAY_GRAMMAR):
print(lesson.title, lesson.date)
# Drill into full lesson detail from a summary
summary = voa.lessonsummary(id="5345471")
detail = summary.details()
print(detail.title, detail.date)
print(detail.vocabulary)
print(detail.media_links)
# Browse a category by ID
cat = voa.category(id="3620")
for article in cat.list_articles():
print(article.title, article.date, article.thumbnail)
Fetch featured stories and highlights from the VOA Learning English homepage. Returns currently promoted content items with their media type and status.
No input parameters required.
{
"type": "object",
"fields": {
"featured_items": "array of featured content objects with id, title, url, type, status, and badge fields"
},
"sample": {
"data": {
"featured_items": [
{
"id": 8154328,
"url": "https://learningenglish.voanews.com/a/8154328.html",
"type": "audio",
"badge": null,
"title": "Learning English Podcast",
"status": "Latest"
}
]
},
"status": "success"
}
}About the Voanews API
Lesson and Article Data
The get_lesson_detail endpoint accepts either a numeric article_id or a full lesson url. Its response includes a sections object mapping section names to paragraph arrays, a transcript array, a vocabulary array with definitions, media_links for downloadable audio and video files, and a quiz_link field that points to an associated quiz when one exists. Article IDs appear in results from search_lessons and get_category_list, making it straightforward to chain calls.
Browsing by Program or Category
get_level_program_list accepts a program parameter with named values such as news_words, everyday_grammar, american_stories, english_in_a_minute, and english_at_the_movies. It returns an array of article objects each containing id, title, url, date, category, and thumbnail. get_category_list works similarly but takes a numeric category_id (for example, 3620 for News Words or 4456 for Everyday Grammar) and supports 0-based page offset pagination with a has_next boolean.
Search and Discovery
search_lessons accepts a required query string plus optional page (1-based) and limit parameters. Results are ordered newest first and include the same article-object shape as category listings. The get_homepage_featured endpoint requires no parameters and returns an array of currently promoted items, each with an id, title, url, type, status, and badge field — useful for surfacing the latest highlighted content without knowing a category or keyword in advance.
The Voanews API is a managed, monitored endpoint for voanews.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when voanews.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 voanews.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 an English-learning app that serves lesson transcripts and vocabulary via
get_lesson_detailfor in-app reading and study. - Index VOA Learning English audio and video files by fetching
media_linksfrom lesson details for a podcast-style player. - Track newly published content across specific programs like
everyday_grammaroramerican_storiesusingget_level_program_list. - Run a keyword search against VOA Learning English content with
search_lessonsto surface articles relevant to a teaching topic. - Display featured homepage stories in a curated feed using
get_homepage_featuredbadge and status fields. - Aggregate vocabulary lists from multiple lessons to generate flashcard sets using the
vocabularyarray returned byget_lesson_detail. - Paginate through a category's full article archive using
get_category_listwithcategory_idand thehas_nextflag for crawl logic.
| 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 VOA Learning English have an official developer API?+
What does `get_lesson_detail` return beyond the article text?+
transcript array of paragraphs (when available), a vocabulary array with definitions drawn from the lesson, an array of media_links pointing to downloadable mp3 and mp4 files, and a quiz_link URL if an associated quiz exists. Either an article_id or a full url must be supplied — both routes return the same response shape.How does pagination differ between `search_lessons` and `get_category_list`?+
search_lessons uses 1-based page numbering via the page parameter and also accepts a limit value, while get_category_list uses a 0-based page offset. Both return a has_next boolean so you can determine whether additional pages exist without guessing.Does the API cover VOA News main-site articles, not just the Learning English subdomain?+
Are user comments or quiz question data included in lesson responses?+
get_lesson_detail response includes a quiz_link URL pointing to an associated quiz page, but the quiz questions and answer data themselves are not returned inline. The API covers article content, transcripts, vocabulary, and media links. You can fork this API on Parse and revise it to add a dedicated quiz-content endpoint.