openapi: 3.1.0
info:
  title: Library of Congress loc.gov JSON API
  description: >-
    The loc.gov JSON API returns structured JSON or YAML representations of
    Library of Congress online collections, items, and search results.
    Append fo=json (or fo=yaml) to most loc.gov URLs to receive a structured
    response describing the page or resource.
  version: 1.0.0
  contact:
    name: Library of Congress
    url: https://www.loc.gov/apis/
servers:
  - url: https://www.loc.gov
    description: Production
paths:
  /search/:
    get:
      operationId: searchAll
      summary: Search loc.gov
      description: Search across the loc.gov website and digital collections.
      tags:
        - Search
      parameters:
        - name: q
          in: query
          description: Search query string.
          schema:
            type: string
        - name: fo
          in: query
          description: Response format (json or yaml).
          schema:
            type: string
            enum:
              - json
              - yaml
            default: json
        - name: c
          in: query
          description: Number of results per page.
          schema:
            type: integer
            default: 25
        - name: sp
          in: query
          description: Page number of results.
          schema:
            type: integer
        - name: at
          in: query
          description: Limit response to specified attributes (comma-separated).
          schema:
            type: string
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
  /collections/:
    get:
      operationId: listCollections
      summary: List Collections
      description: List the Library's digital collections.
      tags:
        - Collections
      parameters:
        - name: fo
          in: query
          schema:
            type: string
            default: json
      responses:
        '200':
          description: Collections list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionList'
  /collections/{name}/:
    get:
      operationId: getCollection
      summary: Get Collection
      description: Retrieve metadata and items for a specific collection.
      tags:
        - Collections
      parameters:
        - name: name
          in: path
          required: true
          description: Collection slug.
          schema:
            type: string
        - name: fo
          in: query
          schema:
            type: string
            default: json
      responses:
        '200':
          description: Collection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
  /item/{itemId}/:
    get:
      operationId: getItem
      summary: Get Item
      description: Retrieve a single item record.
      tags:
        - Items
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
        - name: fo
          in: query
          schema:
            type: string
            default: json
      responses:
        '200':
          description: Item record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
  /resource/{resourceId}/:
    get:
      operationId: getResource
      summary: Get Resource
      description: Retrieve a digitized resource record.
      tags:
        - Resources
      parameters:
        - name: resourceId
          in: path
          required: true
          schema:
            type: string
        - name: fo
          in: query
          schema:
            type: string
            default: json
      responses:
        '200':
          description: Resource record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
components:
  schemas:
    SearchResults:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        pagination:
          type: object
          properties:
            current:
              type: integer
            total:
              type: integer
            of:
              type: integer
        facets:
          type: array
          items:
            type: object
    CollectionList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Collection'
    Collection:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        item_count:
          type: integer
    Item:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        date:
          type: string
        url:
          type: string
          format: uri
        description:
          type: array
          items:
            type: string
        subject:
          type: array
          items:
            type: string
        original_format:
          type: array
          items:
            type: string
    Resource:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        files:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                format: uri
              mimetype:
                type: string