openapi: 3.1.0
info:
  title: Library of Congress Chronicling America API
  description: >-
    The Chronicling America API exposes historic American newspapers
    digitized through the National Digital Newspaper Program, providing
    search and metadata access to newspaper pages, issues, and titles.
  version: 1.0.0
  contact:
    name: Library of Congress
    url: https://chroniclingamerica.loc.gov/about/api/
servers:
  - url: https://chroniclingamerica.loc.gov
    description: Production
paths:
  /search/pages/results/:
    get:
      operationId: searchPages
      summary: Search Pages
      description: Search digitized newspaper pages by keyword and facets.
      tags:
        - Pages
      parameters:
        - name: andtext
          in: query
          description: Phrase to search within page text.
          schema:
            type: string
        - name: state
          in: query
          description: U.S. state filter.
          schema:
            type: string
        - name: dateFilterType
          in: query
          schema:
            type: string
            enum:
              - yearRange
              - range
        - name: date1
          in: query
          schema:
            type: string
        - name: date2
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            enum:
              - json
              - atom
              - html
            default: json
        - name: rows
          in: query
          schema:
            type: integer
            default: 20
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Page search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageResults'
  /search/titles/results/:
    get:
      operationId: searchTitles
      summary: Search Titles
      description: Search newspaper titles by name, place, or other facets.
      tags:
        - Titles
      parameters:
        - name: terms
          in: query
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
        - name: format
          in: query
          schema:
            type: string
            default: json
        - name: rows
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: Title search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TitleResults'
  /lccn/{lccn}.json:
    get:
      operationId: getTitle
      summary: Get Title
      description: Retrieve metadata for a newspaper title by LCCN.
      tags:
        - Titles
      parameters:
        - name: lccn
          in: path
          required: true
          description: Library of Congress Control Number.
          schema:
            type: string
      responses:
        '200':
          description: Title metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Title'
  /lccn/{lccn}/{date}/ed-{edition}.json:
    get:
      operationId: getIssue
      summary: Get Issue
      description: Retrieve metadata for a single issue of a newspaper.
      tags:
        - Issues
      parameters:
        - name: lccn
          in: path
          required: true
          schema:
            type: string
        - name: date
          in: path
          required: true
          description: Issue date in YYYY-MM-DD format.
          schema:
            type: string
        - name: edition
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Issue metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
  /newspapers.json:
    get:
      operationId: listNewspapers
      summary: List Newspapers
      description: List all newspaper titles with digitized content.
      tags:
        - Titles
      responses:
        '200':
          description: Newspaper list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewspaperList'
components:
  schemas:
    PageResults:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Page'
        totalItems:
          type: integer
        startIndex:
          type: integer
        endIndex:
          type: integer
    Page:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        title:
          type: string
        date:
          type: string
        sequence:
          type: integer
        ocr_eng:
          type: string
    TitleResults:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Title'
        totalItems:
          type: integer
    Title:
      type: object
      properties:
        lccn:
          type: string
        name:
          type: string
        place_of_publication:
          type: string
        start_year:
          type: string
        end_year:
          type: string
        url:
          type: string
          format: uri
    Issue:
      type: object
      properties:
        date_issued:
          type: string
        edition:
          type: integer
        title:
          type: object
        pages:
          type: array
          items:
            $ref: '#/components/schemas/Page'
    NewspaperList:
      type: object
      properties:
        newspapers:
          type: array
          items:
            $ref: '#/components/schemas/Title'