# NPR Listening Service API

> NPR Listening Service API on Apizie: 9 endpoints (Get a set of recommendations for an aggregation independent of the user's listening history, Get the list of available channels, Get recent ratings the logged-in user has submitted, Get a list of recommendations from a category of content from an organization, …) returned as clean JSON through one API key. Send your own provider key in the x-upstream-key header. Call it over REST at https://apizie.tech/v1/entertainment:npr-listening/{endpoint} or from Claude, ChatGPT and Cursor through the Apizie MCP server. Free plan: 1,000 requests a month.

- Project key: `entertainment:npr-listening`
- Category: Entertainment
- Status: byok
- Source: https://dev.npr.org
- Page: https://apizie.tech/api/entertainment/npr-listening
- OpenAPI: https://apizie.tech/api/entertainment/npr-listening/openapi.json

Audio recommendations tailored to a user's preferences

## Endpoints

### Get a set of recommendations for an aggregation independent of the user's listening history
`GET https://apizie.tech/v1/entertainment:npr-listening/get-agg-recommendations` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| aggId | integer | yes | ID of an aggregation such as a program or podcast. If the specified ID is a program that publishes rundowns, the latest rundown will be… |
| startNum | integer | no | The result to start with. Allows paging through the episodes of a podcast or program, with the default, `startNum=0`, being the most… |

### Get the list of available channels
`GET https://apizie.tech/v1/entertainment:npr-listening/get-channels` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| exploreOnly | boolean | no | If set to `true`, this call will return only channels that should be shown in the client's `Explore` view |

### Get recent ratings the logged-in user has submitted
`GET https://apizie.tech/v1/entertainment:npr-listening/get-history` (byok)

### Get a list of recommendations from a category of content from an organization
`GET https://apizie.tech/v1/entertainment:npr-listening/get-organization-category` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| orgId | integer | yes | ID of an organization, such as an NPR One station |
| category | string | yes | One of the three categories of content - newscast, story, or podcast |

### Get a variety of details about an organization including various lists of recent audio items
`GET https://apizie.tech/v1/entertainment:npr-listening/get-organization-overview` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| orgId | integer | yes | ID of an organization, such as an NPR One station |

### Retrieve the most recent promo audio heard by the logged-in user
`GET https://apizie.tech/v1/entertainment:npr-listening/get-promo` (byok)

### Collect new ratings for media previously recommended to the logged-in user
`POST https://apizie.tech/v1/entertainment:npr-listening/post-rating` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| X-Advertising-ID | string | no | A device-specific advertising identifier, if possible. Apple's IDFA is an example. |
| channel | string | no | Determines the focus of the recommendations returned. Channel `npr` is recommended for most use cases. |
| recommend | boolean | no | If set to `false`, this call will return a blank document; otherwise it will return a new recommendation object |
| body | object | yes | JSON request body |

### Get a list of media for the logged-in user from NPR's recommendation engine
`GET https://apizie.tech/v1/entertainment:npr-listening/get-recommendations` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| X-Advertising-ID | string | no | A device-specific advertising identifier, if possible. Apple's IDFA is an example. |
| channel | string | no | Determines the focus of the recommendations returned. Channel `npr` is recommended for most use cases. |
| sharedMediaId | string | no | This media was shared directly with the user; if provided, the service will add this recommendation to the top of the list |
| notifiedMediaId | string | no | The user received a push notification about this media; if provided, the service will add this recommendation to the top of the list |

### Get a list of recent audio and aggregation items associated with search terms
`GET https://apizie.tech/v1/entertainment:npr-listening/get-search-recommendations` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| searchTerms | string | yes | Search terms to search on; can include URL-encoded punctuation |

## Example
```
curl "https://apizie.tech/v1/entertainment:npr-listening/get-agg-recommendations" \
  -H "x-api-key: $APIZIE_KEY" \
  -H "x-upstream-key: $PROVIDER_KEY"
```

## FAQ

### How do I call the NPR Listening Service API?
Create a free Apizie key, then send GET https://apizie.tech/v1/entertainment:npr-listening/get-agg-recommendations with the header x-api-key. Every endpoint returns { project, data, timestamp }.

### Is the NPR Listening Service API free on Apizie?
Yes. The Free plan includes 1,000 requests a month at 100 requests a minute, no credit card. NPR Listening Service itself also needs your own key from npr.org.

### Can AI agents use the NPR Listening Service API?
Yes. Add the Apizie MCP server (https://apizie.tech/mcp) to Claude, ChatGPT, Cursor or VS Code, then ask in plain language. The agent calls run_scraper with project key entertainment:npr-listening.

### What is the status of the NPR Listening Service API?
Needs your own provider key (bring your own key)