canonical: https://jentic.com/apis/nytimes.com/most-popular-api

# Nytimes Most Popular API

The New York Times Most Popular API returns the most-emailed, most-shared, and most-viewed NYT articles for the past 1, 7, or 30 days. Three GET endpoints take a section filter and a time-period parameter and respond with ranked article lists including title, byline, abstract, publication date, web URL, and embedded media. The API is a fast way to surface trending NYT coverage and identify the stories generating the most reader engagement.

## For AI agents

Get the most-emailed, most-shared, and most-viewed NYT articles by section over the last 1, 7, or 30 days.

## Scope

Does not provide full article text, comment threads, or sub-daily time windows - use for ranked most-emailed, most-shared, and most-viewed NYT article lists only.

## Capabilities

- Retrieve the most-emailed NYT articles by section and time window
- Pull the most-shared NYT articles filtered by share platform like Facebook
- Get the most-viewed NYT articles for the past 1, 7, or 30 days
- Filter results to a specific NYT section such as Politics or Technology
- Surface ranked engagement signal across all NYT sections at once via section=all-sections
- Pull article media metadata including image URLs and captions

## Use cases

### Trending Stories Widget

Power a homepage or sidebar widget showing the top NYT articles by reader engagement. Each of the three endpoints accepts a section filter (or all-sections) and a time period, returning a ranked list with title, byline, abstract, and image media. A typical integration calls /mostviewed/all-sections/7.json once per hour and caches the response.

Example prompt: Call /mostviewed/all-sections/7.json and return the top 10 articles with title, byline, abstract, and the largest media URL.

### Section Engagement Analysis

Compare engagement across NYT sections by querying each endpoint with different section filters and time periods. The data supports editorial decisions about coverage emphasis and content strategy by surfacing which Politics, Technology, or Opinion stories drive the most viewing, sharing, and emailing.

Example prompt: Loop the section list ['politics','technology','opinion'] and call /mostviewed/{section}/7.json for each, then return the top 5 article titles per section.

### Social Sharing Insights

Identify which NYT articles are being shared on a specific social platform. The /mostshared endpoint supports a share-type segment for Facebook, letting an agent surface platform-specific viral coverage rather than the aggregate engagement signal.

Example prompt: Call /mostshared/all-sections/1.json and return the top 5 articles ranked by aggregate share count.

### Agent-Driven Trending Lookup via Jentic

An AI news assistant uses Jentic to fetch trending NYT articles when a user asks what's getting attention today. Jentic returns the matching Most Popular operation, the agent loads the schema, and executes the call without manually wiring the section/time-period path templates.

Example prompt: Search Jentic for 'get most viewed NYT articles', load the /mostviewed/{section}/{time-period}.json operation, and execute it with section='all-sections' and time-period=1.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /mostemailed/{section}/{time-period}.json | Most emailed NYT articles by section and time period |
| GET | /mostshared/{section}/{time-period}.json | Most shared NYT articles by section and time period |
| GET | /mostviewed/{section}/{time-period}.json | Most viewed NYT articles by section and time period |

## Key resources

- **Most Emailed** — Articles ranked by reader email shares within a chosen section and time window.
- **Most Shared** — Articles ranked by social shares with optional platform filtering.
- **Most Viewed** — Articles ranked by page views within a chosen section and time window.

## Why Jentic

- **Setup:** Wiring the NYT Most Popular API by hand means appending your api-key to the query string against api.nytimes.com/svc/mostpopular/v2 and handling the ranked-list request plumbing yourself. Through Jentic you install once, import the NYT Most Popular API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** The Most Popular API carries only section and time-period in its paths and no resource id, so scope the agent to the operations it needs, such as most-viewed or most-shared, and leave the rest out. You choose the operations it may call, so it only reaches the endpoints you list.
- **Credential handling:** Your NYT api-key is stored once, encrypted, by your own Jentic One instance and injected as the api-key query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get the most viewed NYT articles' or 'find trending NYT stories', and Jentic returns the matching Most Popular operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **NYT Top Stories API** — Editor-curated section front lists rather than reader-engagement ranked lists.
- **NYT Times Newswire API** — Real-time stream of newly published NYT articles paired with engagement-ranked lists.
- **NYT Community API** — Reader comments on the same articles that surface in the Most Popular rankings.

## FAQ

### What authentication does the NYT Most Popular API use?

Authentication is an API key sent as the api-key query parameter on every endpoint. Provision a key at developer.nytimes.com. Through Jentic the credential is held in the vault and injected at execution time, so the agent never holds the raw key.

### Which time periods does this API support?

Each endpoint accepts a time-period path segment of 1, 7, or 30, representing days. There is no support for sub-daily granularity or arbitrary date ranges, so the smallest meaningful refresh window is 24 hours.

### What are the rate limits for the NYT Most Popular API?

NYT enforces 500 requests per day and 5 requests per minute per API key, shared across all NYT developer APIs. The trending list changes slowly, so cache responses for at least 30 minutes to stay well under the limits.

### How do I get the most-viewed Politics articles through Jentic?

Search Jentic for 'get most viewed NYT articles', load the /mostviewed/{section}/{time-period}.json operation, and execute it with section='politics' and time-period=7. The response returns ranked articles with title, byline, abstract, and media URLs.

### Is the NYT Most Popular API free to use?

Yes. NYT offers the Most Popular service at no cost on the developer portal for non-commercial use within published rate limits. Commercial or high-volume use requires direct contact with the NYT licensing team.

### Can I filter most-shared articles by social platform?

Yes. The /mostshared endpoint supports a share-type segment that filters to specific platforms such as Facebook. Without the filter the response aggregates shares across platforms and returns the overall ranking.

### Can I limit what my agent is allowed to do with the NYT Most Popular API?

Yes. Because you run Jentic One yourself, you decide which of this API's three read operations the agent can reach, so you can grant most-viewed only and withhold most-emailed and most-shared. The endpoints carry just a section and time-period in their paths and no resource id, so limiting the operation list is enough to bound exactly what the agent can call. Your NYT api-key is held by your own instance and supplied only when a permitted operation runs, so the agent never sees the raw key or an endpoint you left out.