Interoperability: Linked Data & SearchCulture API

The Hellenic Aggregator of Digital Cultural Heritage Content SearchCulture.gr now has two new ways of publishing data. The Web API allows third-party applications to search for and display data aggregated here. Linked Data is a publishing approach which allows data integration and use.

Linked Data

SearchCulture.gr uses Europeana Data Model (EDM) for the documentation of the digital assets it aggregates. EDM is an RDF model advocated by Europeana for the representation of cultural content metadata.

Metadata in SearchCulture.gr retain semantic links to other data - vocabularies and thesauri- also offered as Linked Data using RDF links to specific EDM model traits. Some links have been defined by the publishers themselves and are included in the original metadata, while others have been added by EKT as part of the semantic enrichment it applies to the content it accumulates. So, most of the digital items maintain inherent links to the GeoNames geographical database. EKT enriched items with links to the Typology Vocabulary that we developed, which in turn links to the Getty Art & Architecture Thesaurus (AAT) and the semantic thesaurus DBpedia of Wikipedia. Moreover, EKT enriched the metadata with links to the Hellenic Historical Periods Vocabulary, which is linked to DBpedia.

Items have unique, permanent HTTP URIs so that they can be referred to by users and applications. An example of a URI is the one below:
https://www.searchculture.gr/aggregator/edm/parthenonfrieze/000077-10442_nxli.

Each item’s URI give us its descriptive metadata in 3 different formats:

  • When a user enters an item’s URI to a common browser he/she will see the HTML item page. The same HTML page will be shown to an HTTP/REST Client if the command includes the value “text/html” in the header parameter “Accept”.

    HTML  

  • If a HTTP/REST Client submits a URI with the value "application/rdf+xml" or "application/xml" in the header parameter “Accept”, he/she will get the RDF item description- according to EDM- in RDF/XML serialization. Alternatively, they can use the ending "/xml" in the URI with no need to define the “Accept” parameter.

    RDF/XML  

  • Finally, by using the value "application/ld+json" or "application/json" in the Header parameter "Accept", the RDF (modelled in EDM) description of the item will be viewed in JSON ( JSON-LD in particular) serialization. Alternatively, they can use the ending "/json" at the item’s URI with no need to define the "Accept" parameter.

    JSON-LD  



SearchCulture API

SearchCulture.gr has a web API that allows third-party applications to search for and view documents hosted by the aggregator. The API offers all the search capabilities provided by the web portal.

To use the API one has to apply for a personal API Key via this form.

The API’s basic URI is the following:

https://www.searchculture.gr/aggregator/api/search.json

You can test the SearchCulture API and the item HTTP URI dereference via the Swagger GUI.

Parameters

Parameters
Name Datatype Description Mandatory
apiKey String The API key which allows one to use the API. To obtain it one has to apply through our form. Yes
general_term String Generic term which will be queried across all metadata fields. Search function is “fuzzy search” which gives results based on unfinished words or phrases. No
ekt_type Array(String) Term from the Vocabulary of Types developed by EKT. Search is based on the “EKT Type” metadata field, which EKT added as part of our semantic enrichment workflow applied to all aggregated content. In the default mode, the suggested names of each term should be used in Greek or in English, provided that the preferredLanguage parameter is "en". Alternatively, the URIs of the terms can be used if the ektFieldsUseURIs parameter has a "false" value. The ekt_type parameter is multiple, meaning that more than one type can be given (eg .. & ekt_type = Vessel & ekt_type = Embossed). In this case, logical coupling (OR) is used, that is, documents that have at least one of the given formulas will be returned. No
ekt_historical_period String Term from the Greek Historical Periods Vocabulary, developed by EKT. Search is based on the metadata field “EKT historical period” which EKT added as part of our semantic enrichment workflow applied to all aggregated content. In default mode one has to use the suggestions for each term in Greek or English, provided that the parameter preferredLanguage has the value "en". Alternatively, the URIs of the terms can be used if the ektFieldsUseURIs parameter has a "false" value. Please note that the parameter ekt_historical_period is not multiple. No
ekt_chronology String The chronology of creation of an item as year (ie 1970) or timespan (ie -600/-400). Search is based on the field “EKT Chronology” which EKT added as part of our semantic enrichment workflow applied to all aggregated content. No
ektStrictPeriodsMode Boolean

When the parameter has “false” value (default), searching with chronological criteria (ekt_chronology or ekt_historical_period) is wider, dealing with items with timespan or historical period which is plainly covered in anyway with the time span or the chronological period of the search. For example when searching the timespan “1500-1600 AD” an item dated “1550-1750 AD” will come up in the results.

When the parameter has “true” value, searching with chronological criteria is strict, resulting in a list of items with the timespan or historical period as prescribed by the search terms. Use this option if you only want items dating strictly within a certain timespan. For example, searching the timespan “1500-1600 AD” will only yield results dating within that, so an item dating “1550 - 1750 AD.” will not show up.

Default value: false

No
ektFieldsUseURIs Boolean

When the parameter has “false” value (default), the values for the parameters ekt_type and ekt_historical_period are the suggested terms (in Greek or English depending on the value of parameter preferredLanguage).

When the parameter has “true” value, the values for parameters ekt_type and ekt_historical_period are the terms’ URIs.

Default value: false

No
dc_type String Search original item type (dc:type) used by the owner institution. Search function is “fuzzy search” which gives results based on unfinished words or phrases. No
dc_subject String Search subject (dc:subject) used by the owner institution. Search function is “fuzzy search” which gives results based on unfinished words or phrases. No
dc_creator_or_dc_contributor String Search creator (dc:creator) or contributor (dc:contributor) used by the owner institution. Search function is “fuzzy search” which gives results based on unfinished words or phrases. No
dcterms_spatial String Search geographical coverage (dcterms:spatial) used by the owner institution. Search function is “fuzzy search” which gives results based on unfinished words or phrases. No
institution String Search items by a specific institution. Acceptable values in this parameter are the official names of institutions in Greek or English as they appear here and here, respectively, depending on the value of parameter preferredLanguage. No
collection String Search items of a specific collection. Acceptable values in this parameter are the official names of collections in Greek or English as they appear here and here, respectively, depending on the value of parameter preferredLanguage. No
rightsCategoryForDigitalFiles String Search based on licensing of digital file (reusability parameter). Acceptable values are the below: RIGHTS_RESERVED, CC_BY, CC_BY_SA, CC_BY_ND, CC_BY_NC, CC_BY_NC_SA, CC_BY_NC_ND No
preferredLanguage String Suggested language with acceptable values "el" (Greek) ή "en" (English). The parameter defines which language the parameter ekt_type, ekt_historical_period, institution and collection values should be. It also defines the language of the values of the respective fields in the search results.

Default value: el

No
page Number Results are paginated with each page consisting of up to 50 entries. This parameter defines the corresponding page.

Default value: 1

No

Results

Τhe response to the SearchCulture API is always formatted in JSON SearchAPIBriefItem 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 SearchAPIBriefItem corresponding with the items. Results are paginated with each page consisting of up to 50 entries. Each item SearchAPIBriefItem includes only some of the metadata fields and the thumbnail URL. It does include the HTTP URI of the item which can be used for obtaining the full item description (as EDM in XML/RDF serialization, as EDM in JSON-LD serialization or as HTML)

SearchAPIResults
Field Datatype Description
apiKey String The authentication parameter sent out by the client
totalResults Number The total number of results
page Number The page number
pageSize Number Number of results per page
results Array(SearchAPIBriefItem) This is a collection of search results SearchAPIBriefItem corresponding to the items
SearchAPIBriefItem
Field Datatype Description
uri String The HTTP URI of the item. It can be used to retrieve the full description of the item as EDM in XML / RDF serialization, as EDM in JSON-LD serialization or as HTML.
dc_title Array(String) The title of the item. Corresponds to the dc:type property of EDM.
ekt_type Array(String) ΕΚΤ type from the Vocabulary of Types. It has been added by EKT as part of the semantic enrichment it applies to the content it accumulates.
ekt_chronology Number ΕΚΤ chronology. It has been added by EKT as part of the semantic enrichment it applies to the content it accumulates.
ekt_historical_period Array(String) ΕΚΤ Historical period from the Greek Historical Periods Vocabulary. It has been added by EKT as part of the semantic enrichment it applies to the content it accumulates.
dc_creator Array(String) The creator of the item. It matches the dc:creator property of EDM.
dc_contributor Array(String) The factor of the item. Corresponds to the dc:contributor property of EDM.
edm_rights String The license of the digital file. Corresponds to edm:rights property of the class ore:Aggregation of EDM.
thumbnail String The preview image URL
aggregator String The Content Aggregator that provides the item (SearchCulture.gr)
institution String The institution holding the item.
collection String The collection the item originates from.
edm_type String The Europeana Type. Corresponds to edm:type attribute of EDM.
edm_isShownAt String The URL of the item page in the institution's repository site.

Request an API Key

To obtain an API key just fill in the form below. As soon as your registration application is authenticated by the SearchCulture.gr team you shall receive an email with the API key.








Terms of use of SearchCulture API

The use of the SearchCulture.gr API is conditioned upon the unreserved acceptance of the Terms of Use (ToU) described henceforth and is construed as an acceptance of these Terms of Use.


Terms of use of SearchCulture API