openapi: 3.0.3 info: title: Digital Public Library of America (DPLA) 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 - name: Primary Source Sets description: Search and retrieve primary source sets (PSS) for education - name: Authentication description: API key registration and management - name: Utilities description: Utility endpoints for health checks and random item retrieval 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' /random: get: operationId: randomItem summary: Retrieve a random item description: >- Returns a single randomly selected cultural heritage item record. Supports an optional filter parameter to constrain the pool of eligible records. tags: - Utilities parameters: - name: filter in: query description: >- Filter expression to constrain the random selection pool. Format is field:value. schema: type: string example: "sourceResource.type:image" - name: api_key in: query description: Your DPLA API key. Alternatively, pass as Authorization header. schema: type: string responses: '200': description: A randomly selected item record content: application/json: schema: $ref: '#/components/schemas/ItemSearchResponse' '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' /pss/sets: get: operationId: searchPssSets summary: Search primary source sets description: >- Search DPLA's Primary Source Sets (PSS) — curated collections of primary source documents designed for classroom use. Returns set metadata including title, description, creator, and source items. tags: - Primary Source Sets parameters: - name: q in: query description: Full-text search query. schema: type: string - name: page in: query description: Page number for pagination. schema: type: integer minimum: 1 default: 1 - name: page_size in: query description: Number of results per page. schema: type: integer minimum: 0 maximum: 500 default: 10 - name: api_key in: query description: Your DPLA API key. schema: type: string responses: '200': description: Successful primary source sets search response content: application/json: schema: $ref: '#/components/schemas/PssSetListResponse' '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' /pss/sets/{id}: get: operationId: fetchPssSet summary: Fetch a single primary source set by ID description: >- Retrieve a complete primary source set record by its identifier, including all source items and educational metadata. tags: - Primary Source Sets parameters: - name: id in: path required: true description: Primary source set identifier. schema: type: string - name: api_key in: query description: Your DPLA API key. schema: type: string responses: '200': description: Successful primary source set fetch content: application/json: schema: $ref: '#/components/schemas/PssSetResponse' '403': description: Forbidden — invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Primary source set not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /pss/sources/{id}: get: operationId: fetchPssSource summary: Fetch primary source items belonging to a set description: >- Retrieve primary source items (hasPart) that belong to a specific primary source set, identified by the set's ID. tags: - Primary Source Sets parameters: - name: id in: path required: true description: Primary source set identifier whose sources to retrieve. schema: type: string - name: api_key in: query description: Your DPLA API key. schema: type: string responses: '200': description: Successful source items response content: application/json: schema: $ref: '#/components/schemas/PssSourceResponse' '403': description: Forbidden — invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /api_key/{email}: post: operationId: createApiKey summary: Request an API key description: >- Self-service API key registration. Submit your email address to receive a free DPLA API key via email. The key is 32 characters, alphanumeric with hyphens, and must be passed as the api_key query parameter or Authorization header on all subsequent requests. tags: - Authentication security: [] parameters: - name: email in: path required: true description: Email address to receive the API key. schema: type: string format: email example: "developer@example.com" responses: '200': description: API key sent to the provided email address content: application/json: schema: type: object properties: message: type: string example: "Your API key has been sent to developer@example.com." '409': description: Conflict — the API key associated with this email is disabled content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /health-check: get: operationId: healthCheck summary: API health check description: Returns HTTP 200 OK if the API is operational. tags: - Utilities security: [] responses: '200': description: API is healthy and operational components: 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). schemas: 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' 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' 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. 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. 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. 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. 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). 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" 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). 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. 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. 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. 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 PssSetListResponse: type: object description: List of primary source sets. properties: "@context": type: string format: uri "@id": type: string format: uri count: type: integer docs: type: array items: $ref: '#/components/schemas/PssSet' PssSetResponse: type: object description: A single primary source set. properties: "@context": type: string format: uri "@id": type: string format: uri docs: type: array items: $ref: '#/components/schemas/PssSet' PssSet: type: object description: A DPLA Primary Source Set record for educational use. properties: "@id": type: string format: uri id: type: string name: type: string description: Title of the primary source set. hasPart: type: array items: type: object properties: "@id": type: string format: uri description: References to source items in this set. about: type: array items: type: object description: Subject topics of this set. creator: type: object description: Organization that created this set. dateCreated: type: string description: Creation date. PssSourceResponse: type: object description: Source items belonging to a primary source set. properties: "@context": type: string format: uri "@id": type: string format: uri docs: type: array items: type: object 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