Search API Documentation
The Search API provides a way to search for metadata records and media on the Europeana repository. For example, you would use the Search API to get a response to the query give me all the results for the word "Vermeer". Additionaly, it provides an alternative method using the OpenSearch.RSS protocol for easier integration with external services.
The Search API is the easiest API to use and understand. It interacts with Europeana's data in much the same way as the Europeana website does. You can search for keywords, and the API will return all records that match that keyword. You can refine your search with more advanced filters and advanced query syntax. You can choose to only return objects with certain copyright statements, or you can choose to return the results in a language of your choice. This means that with the Search API, you can get a response to the query: 'Give me all objects by Vermeer that are openly licensed and have high-resolution images.'
Before starting to use this API, we recommend reading the overview of the Europeana Data Model, registering for an API key, and reading the Terms of Use. If you want to get started with this API, go to the Getting Started section or try some calls using our Swagger Console.
Getting Started
Request
Every call to the Search API is an HTTPS request using the following base URL:
On top of this base URL, you need two required parameters to make a successful Search API request: a query and an API key. to input these required parameters, use “query=” and “wskey=” attached to that URL, using a question mark “?” to separate the parameters from the base URL and an ampersand “&” to separate parameters from each other
api.europeana.eu/record/v2/search.json?query=Vermeer&wskey=yourapikey
Below you’ll find a table with the other standard parameters you can use in your API Search request:
Response
A response from the Search API is always formatted in JSON and will contain fields that present information about the handling of the request, while the concrete information about the record is presented in the "items" field (see Metadata Sets).
Error Responses
An error occurring during processing of an API method is reported by (1) a relevant HTTP status code, (2) a value of the success field and (3) a meaningful error message in the error field. The following table shows the fields appearing within an error response:
The following kinds of error codes can be returned by the Record API:
Query, Filter, and Faceting Fields
Search Fields outside EDM
In addition to the fields defined in EDM, a handful of other administrative fields can also be used to search.
Search Field | Result Field | Description | |
---|---|---|---|
europeana_id | String | id | The Europeana ID of the record. |
timestamp | Date |
|
|
timestamp_created | Date | timestamp_created | The date when record was created (formatted as ISO 8601) |
timestamp_update | Date | timestamp_update | The date when record was last updated (formatted as ISO 8601) |
europeana_completeness | Number | europeanaCompleteness | An internal Europeana measure of the completeness of the metadata of the record, based on the availability of mandatory and optional schema fields. It is measured as a number from 1 to 10 and serves as indicator of the metadata quality. |
COMPLETENESS | String | completeness |
Language-specific Search Fields
In EDM, most of the properties that accept a Literal may be language tagged, meaning the field has a tag that describes the language of the text using the ISO 639-2 standard. To allow for a language-specific search on such properties, the Search API defines a field for each of the language variations that appear in our repository while keeping the base field with all the values in all language variations. As opposed to the base field which typically has datatype Text (some fields may also be defined as String), the language-specific fields are always of type String to allow for faceting with the complete value (with no tokenization), see “datatypes for search fields” below for more details. If a language-specific field is part of a metadata set, it can also be output in the response (see “Language-Specific Result Fields” under the “Metadata Sets” Heading).
The following table shows the base and language-specific search fields for the dc:creator property:
Search Field | Search Datatype | Result Field |
---|---|---|
Text | dcCreator | |
proxy_dc_creator.* | String | dcCreatorLangAware |
Search Fields defined in EDM
EDM defines an extensive list of classes and properties. In the Search API only a subset of these, corresponding to the ones found to be the most commonly used, can be used to search in the repository. These fields are listed in this section.
The ML (ie. multilingual) column of the table below marks the fields that have multilingual variations. To learn more about the type of information that these fields should hold, please refer to the EDM Definition.
Search Field | Search Datatype | Result Field | ML |
---|---|---|---|
proxy_dc_contributor | Text | dcContributor | ✓ |
CONTRIBUTOR | String | dcContributor |
|
proxy_dc_coverage | String |
| ✓ |
proxy_dc_creator | Text | dcCreator | ✓ |
proxy_dc_date | String |
| ✓ |
proxy_dc_description | Text | dcDescription | ✓ |
proxy_dc_format | Text |
| ✓ |
proxy_dc_identifier | String |
| ✓ |
LANGUAGE | String | dcLanguage | ✓ |
proxy_dc_publisher | Text |
| ✓ |
proxy_dc_rights | String |
| ✓ |
proxy_dc_source | String |
| ✓ |
proxy_dc_subject | Text |
| ✓ |
proxy_dc_title | Text | dcTitleLangAware | ✓ |
proxy_dc_type | String |
| ✓ |
proxy_dc_type_search | Text |
| ✓ |
proxy_dcterms_alternative | String |
| ✓ |
proxy_dcterms_created | String |
| ✓ |
proxy_dcterms_hasPart | String | dctermsHasPart | ✓ |
proxy_dcterms_isPartOf | String | dctermsIsPartOf | ✓ |
proxy_dcterms_issued | String |
| ✓ |
proxy_dcterms_medium | Text |
| ✓ |
proxy_dcterms_provenance | String |
| ✓ |
proxy_dcterms_spatial | String | dctermsSpatial | ✓ |
proxy_dcterms_temporal | String |
| ✓ |
proxy_edm_currentLocation | String |
| ✓ |
proxy_edm_hasMet | String |
| ✓ |
proxy_edm_isRelatedTo | String |
| ✓ |
TYPE | String | type |
|
YEAR | String | year | ✓ |
DATA_PROVIDER | String | edmDataProvider | ✓ |
provider_aggregation_edm_hasView |