Digital Public Library of America Items API

openapi: 3.2.0
info:
  title: Digital Public Library of America (DPLA) Authentication Items API
  description: The Digital Public Library of America (DPLA) provides a free REST API that gives access to metadata for 50 million+ cultural heritage items aggregated from 4,000+ US libraries, archives, and museums. The API supports full-text search, field-specific queries, geographic and date range filtering, faceted browsing, and JSONP callbacks. All results are returned as JSON-LD. API keys are issued free of charge via a self-service email-based registration endpoint.
  version: '2'
  contact:
    name: DPLA Developer Portal
    url: https://pro.dp.la/developers
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://dp.la/info/terms-conditions/
servers:
- url: https://api.dp.la/v2
  description: DPLA API v2 production server
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
tags:
- name: Items
  description: Search and retrieve cultural heritage item metadata records
paths:
  /items:
    get:
      operationId: searchItems
      summary: Search cultural heritage items
      description: Search DPLA's aggregated metadata of 50 million+ cultural heritage items from 4,000+ US institutions. Supports full-text search, field-level queries, boolean and wildcard operators, geographic distance queries, date range filtering, and faceted aggregations. Returns JSON-LD records.
      tags:
      - Items
      parameters:
      - name: q
        in: query
        description: Full-text search query. Supports boolean operators (AND, OR, NOT), wildcard characters (* and ?), and phrase matching with quotes.
        schema:
          type: string
        example: Abraham Lincoln
      - name: page
        in: query
        description: Page number for pagination (1-indexed).
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 1
        example: 1
      - name: page_size
        in: query
        description: Number of results per page.
        schema:
          type: integer
          minimum: 0
          maximum: 500
          default: 10
        example: 10
      - name: facets
        in: query
        description: 'Comma-separated list of fields to return as facets (aggregations). Facetable fields include: sourceResource.subject.name, sourceResource.type, sourceResource.format, provider.name, dataProvider.name, sourceResource.language.name, sourceResource.spatial.state, sourceResource.date.begin, rights, admin.contributingInstitution, and others.'
        schema:
          type: string
        example: sourceResource.subject.name,sourceResource.type
      - name: facet_size
        in: query
        description: Maximum number of values to return per facet.
        schema:
          type: integer
          minimum: 0
          maximum: 2000
          default: 50
        example: 50
      - name: fields
        in: query
        description: Comma-separated list of fields to include in each result document. Limits returned fields to the specified subset.
        schema:
          type: string
        example: id,sourceResource.title,sourceResource.creator
      - name: sort_by
        in: query
        description: Field name to sort results by.
        schema:
          type: string
        example: sourceResource.title
      - name: sort_order
        in: query
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        example: asc
      - name: sort_by_pin
        in: query
        description: Geographic coordinate pin (lat,lon) used for distance-based sorting when sort_by is set to a coordinates field.
        schema:
          type: string
        example: 41.3,-73.2
      - name: op
        in: query
        description: Boolean operator used to combine multiple field query terms.
        schema:
          type: string
          enum:
          - AND
          - OR
          default: AND
        example: AND
      - name: exact_field_match
        in: query
        description: When true, field queries match exact values rather than using analyzed/tokenized matching.
        schema:
          type: boolean
          default: false
        example: false
      - name: filter
        in: query
        description: Filter expression to apply to results without affecting relevance scoring. Format is field:value. Can be specified multiple times.
        schema:
          type: string
        example: sourceResource.type:image
      - name: sourceResource.title
        in: query
        description: Filter by title of the cultural heritage item.
        schema:
          type: string
      - name: sourceResource.description
        in: query
        description: Filter by description text.
        schema:
          type: string
      - name: sourceResource.subject.name
        in: query
        description: Filter by subject heading name.
        schema:
          type: string
      - name: sourceResource.creator
        in: query
        description: Filter by creator/author name.
        schema:
          type: string
      - name: sourceResource.contributor
        in: query
        description: Filter by contributor name.
        schema:
          type: string
      - name: sourceResource.publisher
        in: query
        description: Filter by publisher name.
        schema:
          type: string
      - name: sourceResource.type
        in: query
        description: Filter by type (e.g., image, text, sound, moving image, interactive resource, physical object, collection, dataset).
        schema:
          type: string
        example: image
      - name: sourceResource.format
        in: query
        description: Filter by format of the item.
        schema:
          type: string
      - name: sourceResource.language.name
        in: query
        description: Filter by language name.
        schema:
          type: string
      - name: sourceResource.language.iso639_3
        in: query
        description: Filter by ISO 639-3 language code.
        schema:
          type: string
      - name: sourceResource.date.begin
        in: query
        description: Filter by date range begin (ISO 8601 or year).
        schema:
          type: string
      - name: sourceResource.date.end
        in: query
        description: Filter by date range end (ISO 8601 or year).
        schema:
          type: string
      - name: sourceResource.date.after
        in: query
        description: Filter for items dated after the specified value.
        schema:
          type: string
      - name: sourceResource.date.before
        in: query
        description: Filter for items dated before the specified value.
        schema:
          type: string
      - name: sourceResource.spatial.name
        in: query
        description: Filter by geographic location name.
        schema:
          type: string
      - name: sourceResource.spatial.state
        in: query
        description: Filter by US state name.
        schema:
          type: string
        example: California
      - name: sourceResource.spatial.city
        in: query
        description: Filter by city name.
        schema:
          type: string
      - name: sourceResource.spatial.country
        in: query
        description: Filter by country name.
        schema:
          type: string
      - name: sourceResource.spatial.county
        in: query
        description: Filter by county name.
        schema:
          type: string
      - name: sourceResource.spatial.region
        in: query
        description: Filter by region name.
        schema:
          type: string
      - name: sourceResource.spatial.coordinates
        in: query
        description: Filter by geographic coordinates in lat,lon format. Can be used with sort_by_pin for distance-based queries.
        schema:
          type: string
        example: 41.3,-73.2
      - name: provider.name
        in: query
        description: Filter by contributing hub/provider name.
        schema:
          type: string
      - name: provider.@id
        in: query
        description: Filter by provider URI.
        schema:
          type: string
          format: uri
      - name: dataProvider.name
        in: query
        description: Filter by data provider (institution) name.
        schema:
          type: string
      - name: dataProvider.@id
        in: query
        description: Filter by data provider URI.
        schema:
          type: string
          format: uri
      - name: rights
        in: query
        description: Filter by rights statement URI.
        schema:
          type: string
      - name: rightsCategory
        in: query
        description: Filter by rights category.
        schema:
          type: string
      - name: isShownAt
        in: query
        description: Filter by URL where item is shown at the source institution.
        schema:
          type: string
          format: uri
      - name: hasView.@id
        in: query
        description: Filter by URL of a related digital view.
        schema:
          type: string
          format: uri
      - name: id
        in: query
        description: Filter by DPLA item ID.
        schema:
          type: string
      - name: api_key
        in: query
        description: Your DPLA API key. Alternatively, pass as Authorization header. Required for all requests.
        schema:
          type: string
        example: your_32_char_api_key_here_xxxxxx
      responses:
        '200':
          description: Successful search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemSearchResponse'
        '400':
          description: Bad request — invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /items/{id}:
    get:
      operationId: fetchItem
      summary: Fetch a single item by ID
      description: Retrieve the full metadata record for a single cultural heritage item by its DPLA identifier. The item ID is a 32-character hash string. You may also fetch multiple items at once by providing a comma-separated list of up to 50 IDs.
      tags:
      - Items
      parameters:
      - name: id
        in: path
        required: true
        description: DPLA item identifier (32-character hash). For batch retrieval, provide up to 50 comma-separated IDs.
        schema:
          type: string
        example: 1df43d2b1b7b21843abb5f44982f1fef
      - name: api_key
        in: query
        description: Your DPLA API key. Alternatively, pass as Authorization header.
        schema:
          type: string
      responses:
        '200':
          description: Successful item fetch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ItemFetchResponse'
        '403':
          description: Forbidden — invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Item not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    FacetResult:
      type: object
      description: Aggregated facet counts for a specific field.
      properties:
        _type:
          type: string
          description: Type of facet (e.g., "terms", "date_histogram").
          example: terms
        terms:
          type: array
          items:
            $ref: '#/components/schemas/FacetTerm'
          description: List of term/count pairs for a terms facet.
    DateRange:
      type: object
      description: A date or date range associated with the item.
      properties:
        displayDate:
          type: string
          description: Human-readable date string as supplied by the institution.
          example: circa 1865
        begin:
          type: string
          description: Start date (ISO 8601 or year string).
          example: '1865'
        end:
          type: string
          description: End date (ISO 8601 or year string).
          example: '1865'
        after:
          type: string
          description: Date after which results are returned (for filtering).
        before:
          type: string
          description: Date before which results are returned (for filtering).
    Agent:
      type: object
      description: An organization or institution acting as provider or data provider.
      properties:
        '@id':
          type: string
          format: uri
          description: URI identifying the organization.
        name:
          type: string
          description: Name of the organization.
          example: Smithsonian Institution
        exactMatch:
          type: array
          items:
            type: string
            format: uri
          description: URIs that exactly identify this organization.
    ErrorResponse:
      type: object
      description: Standard error response body.
      properties:
        error:
          type: string
          description: Machine-readable error code.
          example: invalid_api_key
        message:
          type: string
          description: Human-readable error description.
          example: Invalid or inactive API key.
        documentation:
          type: string
          format: uri
          description: Link to error documentation.
          example: https://pro.dp.la/developers/responses#errors
      required:
      - error
      - message
    ItemFetchResponse:
      type: object
      description: JSON-LD response for a single DPLA item or batch of items.
      properties:
        '@context':
          type: string
          format: uri
        '@id':
          type: string
          format: uri
        count:
          type: integer
        docs:
          type: array
          items:
            $ref: '#/components/schemas/DPLAItem'
    SubjectTerm:
      type: object
      description: A subject heading term.
      properties:
        '@id':
          type: string
          format: uri
        '@type':
          type: string
        name:
          type: string
          description: Subject heading text.
          example: Presidents -- United States
        scheme:
          type: string
          description: Subject vocabulary scheme (e.g., LCSH).
    DPLAItem:
      type: object
      description: A single DPLA cultural heritage item metadata record (DPLA MAP v4).
      properties:
        '@context':
          type: string
          format: uri
          description: JSON-LD context for this record.
        '@id':
          type: string
          format: uri
          description: Canonical URI for this item in the DPLA.
          example: http://dp.la/api/items/1df43d2b1b7b21843abb5f44982f1fef
        id:
          type: string
          description: DPLA item identifier (32-character hash).
          example: 1df43d2b1b7b21843abb5f44982f1fef
        sourceResource:
          $ref: '#/components/schemas/SourceResource'
        dataProvider:
          $ref: '#/components/schemas/Agent'
        provider:
          $ref: '#/components/schemas/Agent'
        isShownAt:
          type: string
          format: uri
          description: URL at the contributing institution where the item is shown.
        object:
          type: string
          format: uri
          description: URL of the thumbnail or representative image.
        hasView:
          type: array
          items:
            $ref: '#/components/schemas/WebResource'
        iiifManifest:
          type: string
          format: uri
          description: IIIF manifest URL if available.
        rights:
          type: array
          items:
            type: string
            format: uri
          description: Rights statement URIs (e.g., RightsStatements.org or Creative Commons).
        rightsCategory:
          type: string
          description: High-level rights category derived from the rights URI.
        intermediateProvider:
          type: string
          description: Intermediate service provider name, if applicable.
        isPartOf:
          type: object
          properties:
            '@id':
              type: string
              format: uri
            name:
              type: string
          description: Collection or set this item belongs to.
        tags:
          type: array
          items:
            type: string
          description: User-contributed tags associated with this item.
        admin:
          type: object
          properties:
            contributingInstitution:
              type: string
              description: Name of the contributing institution.
        score:
          type: number
          format: float
          description: Relevance score assigned by the search engine.
    FacetTerm:
      type: object
      description: A single facet term with its document count.
      properties:
        term:
          type: string
          description: The facet value.
          example: image
        count:
          type: integer
          description: Number of documents with this value.
          example: 24831
    SourceResource:
      type: object
      description: The intellectual content and descriptive metadata of the original cultural heritage object, following DPLA Metadata Application Profile.
      properties:
        '@id':
          type: string
          format: uri
        title:
          type: array
          items:
            type: string
          description: Title(s) of the item.
          example:
          - Portrait of Abraham Lincoln
        description:
          type: array
          items:
            type: string
          description: Description(s) of the item.
        creator:
          type: array
          items:
            type: string
          description: Creator(s) or author(s).
        contributor:
          type: array
          items:
            type: string
          description: Contributor(s).
        publisher:
          type: array
          items:
            type: string
          description: Publisher(s).
        subject:
          type: array
          items:
            $ref: '#/components/schemas/SubjectTerm'
          description: Subject headings.
        type:
          type: array
          items:
            type: string
          description: 'Object type(s). Common values: image, text, sound, moving image, interactive resource, physical object, collection, dataset.'
        format:
          type: array
          items:
            type: string
          description: Physical or digital format.
        language:
          type: array
          items:
            $ref: '#/components/schemas/Language'
          description: Language(s) of the item.
        date:
          $ref: '#/components/schemas/DateRange'
        temporal:
          $ref: '#/components/schemas/DateRange'
        spatial:
          type: array
          items:
            $ref: '#/components/schemas/SpatialLocation'
          description: Geographic location(s) associated with the item.
        identifier:
          type: array
          items:
            type: string
          description: Local identifier(s) assigned by the contributing institution.
        rights:
          type: array
          items:
            type: string
          description: Rights statement text from the contributing institution.
        relation:
          type: array
          items:
            type: string
          description: Related resources.
        extent:
          type: array
          items:
            type: string
          description: Extent or size of the item.
        collection:
          $ref: '#/components/schemas/Collection'
        subtitle:
          type: array
          items:
            type: string
          description: Subtitle(s) of the item.
        specType:
          type: array
          items:
            type: string
          description: Specific type refinements.
    WebResource:
      type: object
      description: A web-accessible representation or view of the item.
      properties:
        '@id':
          type: string
          format: uri
          description: URL of this web resource.
        format:
          type: string
          description: MIME type or format of this resource.
        rights:
          type: string
          description: Rights statement for this resource.
        edmRights:
          type: string
          format: uri
          description: EDM rights URI for this resource.
    Collection:
      type: object
      description: The collection this item belongs to at the contributing institution.
      properties:
        '@id':
          type: string
          format: uri
        id:
          type: string
          description: Collection identifier.
        title:
          type: string
          description: Collection title.
        description:
          type: string
          description: Collection description.
    Language:
      type: object
      description: Language of the item.
      properties:
        name:
          type: string
          description: Language name.
          example: English
        iso639_3:
          type: string
          description: ISO 639-3 three-letter language code.
          example: eng
    SpatialLocation:
      type: object
      description: A geographic location associated with the item.
      properties:
        name:
          type: string
          description: Place name.
        city:
          type: string
          description: City name.
        county:
          type: string
          description: County name.
        region:
          type: string
          description: Region name.
        state:
          type: string
          description: US state name.
        country:
          type: string
          description: Country name.
        coordinates:
          type: string
          description: Geographic coordinates in "lat,lon" format.
          example: 38.9072,-77.0369
        iso3166-2:
          type: string
          description: ISO 3166-2 subdivision code.
    ItemSearchResponse:
      type: object
      description: JSON-LD response envelope for a list of DPLA item records.
      properties:
        '@context':
          type: string
          format: uri
          description: JSON-LD context URI for DPLA Metadata Application Profile.
          example: http://dp.la/api/items/context
        '@id':
          type: string
          format: uri
          description: URI of this result set.
        count:
          type: integer
          description: Total number of records matching the query.
          example: 128450
        start:
          type: integer
          description: Index of the first result in this page (0-indexed).
          example: 0
        limit:
          type: integer
          description: Number of results in this page.
          example: 10
        docs:
          type: array
          description: Array of DPLA item metadata records.
          items:
            $ref: '#/components/schemas/DPLAItem'
        facets:
          type: object
          description: Facet aggregation results keyed by field name. Only present when the facets query parameter is used.
          additionalProperties:
            $ref: '#/components/schemas/FacetResult'
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: DPLA API key passed as a query parameter. Obtain a free key by sending a POST to /api_key/{email}.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Authorization
      description: DPLA API key passed as an Authorization header value (not Bearer scheme — just the raw 32-character key).