# Voanews — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access VOA Learning English lessons, programs, and vocabulary across all proficiency levels, search for specific content, and retrieve detailed lesson information with transcripts. Browse featured homepage content and explore lessons by category to find the perfect English learning materials for your level.

**Category:** Education | **Website:** [voanews.com/](https://voanews.com/) | **Docs:** [parse.bot/marketplace/2419912b-204c-49a3-9c49-b0c87b5a7853/voanews-com-api](https://parse.bot/marketplace/2419912b-204c-49a3-9c49-b0c87b5a7853/voanews-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-voanews-com-api-2419912b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_category_list

Fetch lessons for a specific category ID from the VOA site. Returns paginated article listings. The page parameter is 0-based. Use category IDs from known mappings (e.g. 3620 for News Words, 4456 for Everyday Grammar, 987 for Words and Stories).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Numeric category ID (e.g. '3620' for News Words, '4456' for Everyday Grammar, '987' for Words and Stories) |
| `page` | integer | No | Page offset for results (0-based) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-voanews-com-api-2419912b/get_category_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","page":"<integer>"}'
```

### get_homepage_featured

Fetch featured stories and highlights from the VOA Learning English homepage. Returns currently promoted content items with their media type and status.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-voanews-com-api-2419912b/get_homepage_featured \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_lesson_detail

Get full details for a lesson or article, including transcript, vocabulary, and media links. Either article_id or url must be provided. The article ID can be extracted from any VOA Learning English article URL (the numeric portion before .html).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `article_id` | string | No | Numeric article ID (e.g. '5345471'). Can be obtained from search_lessons or get_category_list results. |
| `url` | string | No | Full URL of the lesson page (e.g. 'https://learningenglish.voanews.com/a/grammar-games-at-home-part-1-jeopardy/5345471.html') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-voanews-com-api-2419912b/get_lesson_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"article_id":"<string>","url":"<string>"}'
```

### get_level_program_list

Get a list of articles for a specific VOA Learning English program or level. Supports category-based programs (news_words, words_and_stories, everyday_grammar, everyday_grammar_tv, ask_a_teacher, english_at_the_movies, english_in_a_minute, how_to_pronounce, american_stories, arts_and_culture, science_and_technology, health_and_lifestyle, education_tips, learning_english_podcast, as_it_is) and static page programs (beginning_level, intermediate_level, advanced_level, us_history, americas_presidents, lets_teach_english, news_literacy, lets_learn_english_level_1, lets_learn_english_level_2, lets_learn_english_anna, americas_national_parks). Returns a single page of articles.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `program` | string | Yes | Program name identifier |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-voanews-com-api-2419912b/get_level_program_list \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"program":"<string>"}'
```

### search_lessons

Full-text search across VOA Learning English content by keyword. Results ordered by newest first. Paginates via integer page number. Each result includes article ID, title, URL, date, and thumbnail.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Number of results per page |
| `page` | integer | No | Page number (1-based) |
| `query` | string | Yes | Search keyword or phrase |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-voanews-com-api-2419912b/search_lessons \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","page":"<integer>","query":"<string>"}'
```