New York Times Getting Started: API Access & First Request (2026)

Getting started overview

This guide provides a focused walkthrough for developers to quickly get started with the New York Times APIs. It covers the essential steps from creating an account and acquiring API keys to executing your first successful API request. The New York Times offers a suite of APIs designed for accessing a wide range of content, including historical articles, real-time news, and specific content categories like books and community data New York Times API overview. Understanding how to properly authenticate and structure your initial requests is fundamental for integrating New York Times content into your applications or research.

The New York Times developer program provides a free tier that allows up to 500 requests per day and 10,000 requests per month across all APIs New York Times API pricing details. This free tier is suitable for initial development, testing, and projects with moderate usage requirements. For applications requiring higher request volumes, custom enterprise pricing is available.

Here's a quick reference table outlining the getting started process:

Create an account and get keys

Accessing the New York Times APIs requires a developer account and an API key. This key authenticates your requests and tracks your usage against the free tier limits or your paid plan.

Step 1: Register for a Developer Account

1. Navigate to the New York Times Developer website.
2. Click on the 'Sign Up' or 'Register' option.
3. Provide the required information, including your email address and a password.
4. Verify your email address if prompted. This typically involves clicking a link sent to your registered email.

Step 2: Register an Application and Obtain an API Key

Once your account is active, you need to register an application to generate your API key.

1. Log in to your New York Times Developer dashboard.
2. Look for a section like 'Apps' or 'My Applications'.
3. Click 'Create New App' or a similar button.
4. Provide a descriptive name for your application (e.g., "My News Reader App").
5. Select the APIs you intend to use. For a first request, you might select the 'Article Search API' or 'Top Stories API'. You can modify API access later.
6. Submit the application registration form.
7. Upon successful registration, your API key will be displayed. This key is a unique string of characters. Copy this key and store it securely. You will use this key in every API request to the New York Times.

The New York Times developer documentation provides further details on API key management and authentication.

Your first request

After obtaining your API key, you can make your first API call. For this example, we will use the Article Search API to search for articles containing a specific query. The Article Search API allows you to retrieve articles from the New York Times archive based on various criteria Article Search API overview.

Example: Search for articles about "artificial intelligence"

We will use cURL for the initial request, as it is a widely available command-line tool for making HTTP requests and is useful for testing API endpoints cURL man page. Replace YOUR_API_KEY with the actual API key you generated.

cURL Example

curl -X GET "https://api.nytimes.com/svc/search/v2/articlesearch.json?q=artificial%20intelligence&api-key=YOUR_API_KEY"

Explanation of the cURL command:

• curl -X GET: Specifies that this is an HTTP GET request.
• "https://api.nytimes.com/svc/search/v2/articlesearch.json?q=artificial%20intelligence&api-key=YOUR_API_KEY": This is the endpoint URL.
• https://api.nytimes.com/svc/search/v2/articlesearch.json: The base URL for the Article Search API.
• ?q=artificial%20intelligence: A query parameter (q) specifying the search term. Note that spaces are URL-encoded as %20.
• &api-key=YOUR_API_KEY: The query parameter for your API key.

Python Example

For a programmatic approach, here's how you can make the same request using Python's requests library:

import requests
import json

api_key = "YOUR_API_KEY"
query = "artificial intelligence"
url = f"https://api.nytimes.com/svc/search/v2/articlesearch.json?q={query}&api-key={api_key}"

response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
    # You can further process the 'data' dictionary here
    # For example, print the lead paragraph of the first article:
    # if data['response']['docs']:
    #     print(data['response']['docs'][0]['lead_paragraph'])
else:
    print(f"Error: {response.status_code} - {response.text}")

Node.js Example

Using Node.js with the node-fetch library (or built-in fetch in newer Node.js versions):

const fetch = require('node-fetch'); // For older Node.js versions

const apiKey = "YOUR_API_KEY";
const query = "artificial intelligence";
const url = `https://api.nytimes.com/svc/search/v2/articlesearch.json?q=${encodeURIComponent(query)}&api-key=${apiKey}`;

async function fetchArticles() {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    const data = await response.json();
    console.log(JSON.stringify(data, null, 2));
    // Process data here
  } catch (error) {
    console.error("Error fetching articles:", error);
  }
}

fetchArticles();

Upon a successful request, the API will return a JSON object containing an array of article documents matching your query. The structure of the response includes metadata and the actual article content, such as headlines, lead paragraphs, publication dates, and URLs.

Common next steps

After successfully making your first API call, consider these next steps to further integrate with the New York Times APIs:

• Explore other APIs: The New York Times offers several other APIs, including the Books API for best-seller lists, the Times Newswire API for recent articles, and the Top Stories API for current top news. Each serves different content needs.
• Pagination and Filtering: Learn how to use query parameters for pagination (e.g., page parameter) to retrieve more results and apply filters (e.g., begin_date, end_date, fq for filtering by specific fields) to refine your search results.
• Error Handling: Implement robust error handling in your application to gracefully manage API rate limits, invalid API keys, or other common API errors. The New York Times API typically returns HTTP status codes and detailed error messages in JSON format.
• Rate Limit Management: Be mindful of the API rate limits. For higher usage, consider upgrading your plan or implementing client-side caching strategies to reduce the number of requests.
• Data Parsing and Display: Develop logic to parse the JSON responses and extract the specific data points you need for your application, such as article titles, summaries, and links.
• Security Best Practices: Ensure your API key is kept confidential and not exposed in client-side code or public repositories. For server-side applications, use environment variables or a secure configuration management system.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips:

• Check API Key: Double-check that your API key is correct and has been properly included in the api-key query parameter. Typos or missing characters are common causes of authentication failures.
• URL Encoding: Ensure that any special characters in your query parameters (like spaces in search terms) are correctly URL-encoded. For example, a space should be %20. Most HTTP client libraries handle this automatically, but manual cURL requests require it.
• Rate Limits: If you receive a 429 Too Many Requests status code, you have likely exceeded your API's rate limit. Wait a few minutes before trying again, or review your usage on the developer dashboard. The free tier has limits of 500 requests per day and 10,000 per month New York Times API rate limits.
• HTTP Status Codes: Pay attention to the HTTP status code in the API response:
  • 200 OK: Success.
  • 400 Bad Request: Indicates an issue with your request parameters (e.g., missing required parameters, invalid format).
  • 401 Unauthorized: Typically means an invalid or missing API key.
  • 403 Forbidden: Your API key may not have access to the specific API endpoint requested, or there's a general access issue.
  • 404 Not Found: The requested endpoint does not exist. Check the URL for typos.
  • 500 Internal Server Error: An issue on the New York Times server side.
• Consult Documentation: Refer to the official New York Times API documentation for specific endpoint details, required parameters, and common error messages.
• Environment Variables: Consider storing your API key as an environment variable rather than hardcoding it into your script. This is a common security practice, as detailed in guides for secure API key management Google Cloud API key best practices.