Interoperability: Linked Data & SearchCulture API
The Hellenic Aggregator of Digital Cultural 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.
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”.
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.
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.
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.
| 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_subject | Array(String) | Term from the Vocabulary of Subjects developed by EKT. Search is based on the “EKT Subject” 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_subject parameter is multiple, meaning that more than one type can be given (eg .. & ekt_subject = War & ekt_type = Education). 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_place | Array(String) | Term from the Vocabulary of Places developed by EKT. Search is based on the "EKT Place" 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_place parameter is multiple, meaning that more than one places can be given (eg .. & ekt_place=Athens&ekt_place=Paris). 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_person | String | Term from the Notable Persons in Greek History and Culture developed by EKT. Search is based on the “EKT Person” 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_person parameter is multiple, meaning that more than one type can be given (eg .. & ekt_person = Venizelos Eleftherios & ekt_person = Kolettis Ioannis). 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_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 | |
| ektStrictPeriodsMode | String | Defines whether persons given in ekt_person are creators or related persons (reference): AS_CREATOR: Creator AS_REFERENCES: Reference AS_REFERENCES_OR_CREATORS: Creator or reference |
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 |
Τ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)
| 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 |
| 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) | EKT 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_subject | Array(String) | EKT subject from the Vocabulary of Subjects. It has been added by EKT as part of the semantic enrichment it applies to the content it accumulates. |
| ekt_place | Array(String) | EKT place from the Vocabulary of Places. It has been added by EKT as part of the semantic enrichment it applies to the content it accumulates. |
| ekt_person_creator | Array(String) | EKT person / creator from the Notable Persons in Greek History and Culture. It has been added by EKT as part of the semantic enrichment it applies to the content it accumulates. |
| ekt_person_references | Array(String) | EKT person / reference from the Notable Persons in Greek History and Culture. It has been added by EKT as part of the semantic enrichment it applies to the content it accumulates. |
| ekt_chronology | Number | EKT 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) | EKT 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. |
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.
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.
