Versions Compared

Version Old Version 9 New Version 10
Changes made by

Jolan Wuyts

Jolan Wuyts

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Expand
titleSearch API Request Parameters

Parameter

Datatype

Description

query

String

The search term(s). See Query Syntax for information on forming complex queries and examples.

qf

String

Query Refinement. This parameter can be defined more than once. See Query Syntax page for more information.

reusability

String

Filter by copyright status. Possible values are open, restricted or permission.

media

Boolean

Filter by records where an URL to the full media file is present in the edm:isShownBy or edm:hasView metadata and is resolvable.

thumbnail

Boolean

Filter by records where a thumbnail image has been generated for any of the WebResource media resources (thumbnail available in the edmPreview field).

landingpage

Boolean

Filter by records where the link to the original object on the providers website (edm:isShownAt) is present and verified to be working.

colourpalette

String

Filter by images where one of the colours of an image matches the provided colour code. You can provide this parameter multiple times, the search will then do an 'AND‘AND' search on all the provided colours. See: Colour Palette“Colour Palette” under “query, filter and faceting fields”

theme

String

Restrict the query over one of the Europeana Thematic Collections. The possible values are: archaelogy archaeology, art, fashion, industrial, manuscript, map, migration, music, nature, newspaper, photography, sport, ww1.

sort

String

Sorting records in ascending or descending order of search fields. The following fields are supported: score (relenvancy relevancy of the search result), timestamp_created, timestamp_update, europeana_id, COMPLETENESS, is_fulltext, has_thumbnails, and has_media. Sorting on more than one field is possible by supplying as using comma-separated values. It is also possible to randomly order items by using the keyword "random" instead of a field name. You can also request for a fixed random order by indicating a seed "random_SEED" which is useful when paginating along the same randomized order. Use: field_name+sort_order.
Examples:
sort=timestamp_update+desc
sort=random+asc
sort=random_12345+asc

profile

String

A profile parameter which controls the format and richness of the response.

rows

Number

The number of records to return. Maximum is 100. Defaults to 12. See pagination.

start

Number

The item in the search results to start with when using cursor-based pagination. First item is 1. Defaults to 1.

cursor

String

A cursor mark from where to start the search result set when using deep pagination. Set to * to start cursor-based pagination.

callback

String

Name of a client side callback function, see JSONP.

Expand
titleExample: Search for all openly licensed records with a direct link to the full media file:

Request:

https://api.europeana.eu/record/v2/search.json?query=Paris&reusability=open&media=true
(Try on Console)&wskey=YOURAPIKEY

Response

A response from the Search API is always formatted in JSON and will contain a number of 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).

Expand
titleSearch API Response Parameters

Field

Datatype

Description

apikey

String

the authentication parameter sent out by the client (the wskey parameter)

action

String

the name of the API method that was called

success

Boolean

a boolean (true/false) flag denoting the successful execution of the call

statsDuration

Number

the time (in milliseconds) taken to serve the request

requestNumber

Number

a positive number denoting the number of request by this API key within the last 24 hours

params

Object

The original request parameters. If an invalid request parameter was submitted, this response parameter will contain the default value (see individual calls for the default values). Shown up only if the profile parameter contains "params".

itemsCount

Number

The number of retrieved records

totalResults

Number

The total number of results

nextCursor

String

Encoded string to pass along to the cursor to navigate to the next page in the search result set. See Pagination.

items

Array (Item)

This is a collection of search results. Each item is represented by a summary of the metadata record. The actual content is dependent of the profile parameter.

facets

Array (Facet)

A collection of facets that describe the resultant dataset.

breadcrumbs

Array (Breadcrumb)

A collection of search queries that were applied in this call.

...

Expand
titleList of error responses

Field

Datatype

Description

apikey

String

The authentication parameter sent out by the client (the wskey parameter)

success

Boolean

A boolean (true/false) flag denoting the successful execution of the call

statsDuration

Number

The time (in milliseconds) taken to serve the request

error

String

If the call was not successful, this fields will contain a detailed text message. See Error Codes for more information.

The following kinds of errors error codes can be returned by the Record API:

...

Expand
titleExample: Request to the Search API supplying an invalid (unknown) API key

Request:

https://api.europeana.eu/record/v2/search.json?query=*&wskey=test

Response:

Code Block
{
    "apikey": "test",
    "success": false,
    "error": "Invalid API key"
}

...

Expand
titleList of Search fields outside of EDM

Search Field

Datatype

Result Field

Description

europeana_id

String

id

The Europeana ID of the record.

timestamp

Date

timestamp_created

Date

timestamp_created
timestamp_created_epoch

The date when record was created (formatted as ISO 8601)

timestamp_update

Date

timestamp_update
timestamp_update_epoch

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 having a language code that determine 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 “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

proxy_dc_creator

Text

dcCreator

proxy_dc_creator.*

String

dcCreatorLangAware

Search Fields defined in EDM

EDM defines an extensive list of class 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 a

Expand
titleList of Search Fields defined in EDM

Search Field

Search Datatype

Result Field

ML

ore:Proxy

proxy_dc_contributor

Text

dcContributor

✓

CONTRIBUTOR

String

dcContributor

proxy_dc_coverage

String

✓

proxy_dc_creator

Text

dcCreator
dcCreatorLangAware

✓

proxy_dc_date

String

✓

proxy_dc_description

Text

dcDescription
dcDescriptionLangAware

✓

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

✓

ore:Aggregation

DATA_PROVIDER

String

edmDataProvider

✓

provider_aggregation_edm_hasView

String

provider_aggregation_edm_intermediateProvider

String

✓

provider_aggregation_edm_isShownAt

String

edmIsShownAt

provider_aggregation_edm_isShownBy

String

edmIsShownBy

provider_aggregation_edm_object

String

edmObject

PROVIDER

String

provider

✓

provider_aggregation_dc_rights

String

✓

RIGHTS

String

rights

✓

UGC

Boolean

ugc

edm_previewNoDistribute

Boolean

previewNoDistribute

edm:EuropeanaAggregation

europeana_collectionName1

String

europeanaCollectionName

edm_datasetName

String

edmDatasetName

COUNTRY

String

country

✓

europeana_aggregation_edm_language

String

language

✓

edm:WebResource

edm_webResource

String

wr_dc_rights

String

✓

wr_dcterms_isReferencedBy

String

✓

wr_edm_isNextInSequence

String

wr_edm_rights

String

✓

wr_svcs_hasservice

String

✓

cc:License

wr_cc_license

String

provider_aggregation_cc_license

String

provider_aggregation_odrl_inherited_from

String

wr_cc_odrl_inherited_from

String

wr_cc_deprecated_on

Date

provider_aggregation_cc_deprecated_on

Date

svcs:Service

svcs_service

String

sv_dcterms_conformsTo

String

edm:Agent

edm_agent

String

edmAgent

ag_skos_prefLabel

Text

edmAgentLabel

✓

ag_skos_altLabel

Text

✓

ag_foaf_name

String

✓

ag_rdagr2_dateOfBirth

String

✓

ag_rdagr2_dateOfDeath

String

✓

ag_rdagr2_placeOfBirth

Text

✓

ag_rdagr2_placeOfDeath

Text

✓

ag_rdagr2_professionOrOccupation

String

✓

skos:Concept

skos_concept

String

edmConceptTerm

cc_skos_prefLabel

String

edmConceptPrefLabel

✓

cc_skos_altLabel

String

✓

edm:Place

edm_place

String

edmPlace

pl_wgs84_pos_lat

String

edmPlaceLatitude

pl_wgs84_pos_long

String

edmPlaceLongitude

pl_wgs84_pos_alt

String

pl_skos_prefLabel

Text

edmPlaceLabel

✓

pl_skos_altLabel

Text

edmPlaceAltLabel

✓

edm:TimeSpan

edm_timespan

String

edmTimespan

ts_skos_prefLabel

String

edmTimespanLabel

✓

ts_skos_altLabel

String

✓

Notes:

1 This field has been deprecated with edmDatasetName. This change followed the change in EDM to rename to edm:collectionName to edm:datasetName. We will keep support for edmCollectionName for a grace period, but on January 2018, we will return only edmDatasetName so please update your API client.

...