Use the Article Search API to look up articles by keyword. You can refine your search using filters and facets. The API searches NYT articles from September 18, 1851 to today, retrieving headlines, abstracts, lead paragraphs, links to associated multimedia and other article metadata.
openapi: 3.0.0
servers:
- url: http://api.nytimes.com/svc/search/v2
- url: https://api.nytimes.com/svc/search/v2
info:
description: |-
With the Article Search API, you can search New York Times articles from Sept. 18, 1851 to today, retrieving headlines, abstracts, lead paragraphs, links to associated multimedia and other article metadata.
Note: In URI examples and field names, italics indicate placeholders for variables or values. Brackets [ ] indicate optional items. Parentheses ( ) are not a convention — when URIs include parentheses, interpret them literally.
termsOfService: http://developer.nytimes.com/tou
title: The New York Times Article Search API
version: 1.0.0
x-apiClientRegistration:
url: http://developer.nytimes.com/signup
x-apisguru-categories:
- media
- open_data
x-logo:
url: https://api.apis.guru/v2/cache/logo/https_static01.nyt.com_images_icons_t_logo_291_black.png
x-origin:
- format: openapi
url: https://raw.githubusercontent.com/nytimes/public_api_specs/master/article_search/article_search_v2.json
version: "3.0"
x-providerName: nytimes.com
x-serviceName: article_search
externalDocs:
url: http://developer.nytimes.com/
security:
- apikey: []
paths:
/articlesearch.json:
get:
description: |
Article Search requests use the following URI structure:
parameters:
- description: |
Search query term. Search is performed on the article body, headline and byline.
in: query
name: q
required: false
schema:
type: string
- description: |
"Filtered search query using standard Lucene syntax.
The filter query can be specified with or without a limiting field: label.
See Filtering Your Search for more information about filtering."
in: query
name: fq
required: false
schema:
type: string
- description: |
"Format: YYYYMMDD
Restricts responses to results with publication dates of the date specified or later."
in: query
name: begin_date
required: false
schema:
type: string
- description: |
"Format: YYYYMMDD
Restricts responses to results with publication dates of the date specified or earlier."
in: query
name: end_date
required: false
schema:
type: string
- description: |
"By default, search results are sorted by their relevance to the query term (q). Use the sort parameter to sort by pub_date."
in: query
name: sort
required: false
schema:
enum:
- newest
- oldest
type: string
- description: |
"Comma-delimited list of fields (no limit)
Limits the fields returned in your search results. By default (unless you include an fl list in your request), the following fields are returned:
web_url
snippet
lead_paragraph
abstract
print_page
blog
source
multimedia
headline
keywords
pub_date
document_type
news_desk
byline
type_of_material
_id
word_count"
in: query
name: fl
required: false
schema:
type: string
- description: |
Enables highlighting in search results. When set to true, the query term (q) is highlighted in the headline and lead_paragraph fields.
Note: If highlighting is enabled, snippet will be returned even if it is not specified in your fl list."
in: query
name: hl
required: false
schema:
default: false
type: boolean
- description: |
"The value of page corresponds to a set of 10 results (it does not indicate the starting number of the result set). For example, page=0 corresponds to records 0-9. To return records 10-19, set page to 1, not 10."
in: query
name: page
required: false
schema:
default: 0
maximum: 10
minimum: 0
type: integer
- description: |
Comma-delimited list of facets
Specifies the sets of facet values to include in the facets array at the end of response, which collects the facet values from all the search results. By default no facet fields will be returned. Below is the list of valid facets:
section_name
document_type
type_of_material
source
day_of_week
To learn more about using facets, see Using Facets.
in: query
name: facet_field
required: false
schema:
type: string
- description: |
When set to true, facet counts will respect any applied filters (fq, date range, etc.) in addition to the main query term. To filter facet counts, specifying at least one facet_field is required. To learn more about using facets, see Using Facets.
in: query
name: facet_filter
required: false
schema:
default: false
type: boolean
responses:
"200":
content:
application/json:
schema:
properties:
response:
properties:
docs:
items:
$ref: "#/components/schemas/Doc"
type: array
meta:
properties:
hits:
type: integer
offset:
type: integer
time:
type: integer
type: object
type: object
type: object
description: The docs requested by the article search.
summary: The New York Times Article Search
tags:
- Stories
components:
schemas:
Doc:
properties:
_id:
type: string
abstract:
type: string
blog:
items: {}
type: array
byline:
properties:
organization:
type: string
original:
type: string
person:
items: {}
type: array
type: object
document_type:
type: string
headline:
properties:
kicker:
type: string
main:
type: string
type: object
keywords:
properties:
name:
type: string
rank:
type: string
value:
type: string
type: object
lead_paragraph:
type: string
multimedia:
items:
properties:
caption:
type: string
copyright:
type: string
format:
type: string
height:
type: integer
subtype:
type: string
type:
type: string
url:
type: string
width:
type: integer
type: object
type: array
news_desk:
type: string
print_page:
type: string
pub_date:
type: string
section_name:
type: string
slideshow_credits:
type: string
snippet:
type: string
source:
type: string
subsection_name:
type: string
type_of_material:
type: string
web_url:
type: string
word_count:
type: string
type: object
securitySchemes:
apikey:
in: query
name: api-key
type: apiKey
tags:
- name: Stories