openapi: 3.0.0 info: description: The Archive API provides lists of NYT articles by month going back to 1851. You can use it to build your own local database of NYT article metadata. termsOfService: http://developer.nytimes.com/tou title: The New York Times Archive Stories 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/archive_api/archive_api.json version: '3.0' x-providerName: nytimes.com x-serviceName: archive servers: - url: http://api.nytimes.com/svc/archive/v1 - url: https://api.nytimes.com/svc/archive/v1 security: - apikey: [] tags: - name: Stories 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. \n\nThe filter query can be specified with or without a limiting field: label. \n\nSee Filtering Your Search for more information about filtering.\"\n" in: query name: fq required: false schema: type: string - description: "\"Format: YYYYMMDD \n\nRestricts responses to results with publication dates of the date specified or later.\"\n" in: query name: begin_date required: false schema: type: string - description: "\"Format: YYYYMMDD \n\nRestricts responses to results with publication dates of the date specified or earlier.\"\n" 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)\n\n Limits the fields returned in your search results. By default (unless you include an fl list in your request), the following fields are returned: \n \n web_url\n \n snippet\n \n lead_paragraph\n \n abstract\n \n print_page\n \n blog\n \n source\n \n multimedia\n \n headline\n \n keywords\n \n pub_date\n \n document_type\n \n news_desk\n \n byline\n \n type_of_material\n \n _id\n \n word_count\"\n" 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 /{section}.json: get: tags: - Stories summary: The New York Times Top Stories description: 'The Top Stories API returns an array of articles currently on the specified section. ' parameters: - name: section in: path description: The section the story appears in. required: true schema: type: string default: home enum: - arts - automobiles - books/review - business - fashion - food - health - home - insider - magazine - movies - nyregion - obituaries - opinion - politics - realestate - science - sports - sundayreview - technology - theater - t-magazine - travel - upshot - us - world responses: '200': description: An array of articles. content: application/json: schema: type: object properties: status: type: string copyright: type: string section: type: string last_updated: type: string num_results: type: integer results: type: array items: $ref: '#/components/schemas/Article' '401': description: Unauthorized request. Make sure api-key is set. content: {} '429': description: Too many requests. You reached your per minute or per day rate limit. content: {} 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 Article: type: object properties: section: type: string subsection: type: string title: type: string abstract: type: string url: type: string uri: type: string byline: type: string item_type: type: string updated_date: type: string created_date: type: string published_date: type: string material_type_facet: type: string kicker: type: string des_facet: type: array items: type: string org_facet: type: array items: type: string per_facet: type: array items: type: string geo_facet: type: array items: type: string multimedia: type: array items: type: object properties: url: type: string format: type: string height: type: integer width: type: integer type: type: string subtype: type: string caption: type: string copyright: type: string short_url: type: string securitySchemes: apikey: in: query name: api-key type: apiKey externalDocs: url: http://developer.nytimes.com/