### Getting Started with Europeana APIs Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2385313793 Information on how to get started, including obtaining an API key and reading terms of use. ```APIDOC ## Getting Started To begin using the Europeana APIs, follow these steps: ### 1. Get an API Key An API key is required to access most of the Europeana APIs. You can obtain one by visiting the following link: [Link to API Key Request Page] ### 2. Read the Terms of Use Before using the APIs, please review the terms and conditions that govern their usage: [Link to Terms of Use] ### 3. Training and Resources * **Introduction to Europeana APIs Course**: Available on the Europeana Academy. * **User Guides and Training**: Comprehensive guides for using the APIs. * **FAQ**: Frequently Asked Questions to address common queries. ``` -------------------------------- ### Testing with Curl Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2168848385/How%2Bto%2Bconfirm%2Bif%2Byour%2Bvocabulary%2Bsupports%2Bcontent%2Bnegotiation?atlOrigin=eyJpIjoiMzIyMjQ0ZTA1OTgxNDdjZDg3MDVhNWU1YWEyMDJlMjMiLCJwIjoiYyJ9 Provides a command-line example using Curl to test content negotiation. This command sends an HTTP GET request with a specified 'Accept' header to check the server's response. ```bash curl -H "Accept: application/rdf+xml" http://viaf.org/viaf/110233335 ``` -------------------------------- ### Example of edm:begin Property Usage Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/3297116185/EDM%2Bnamespace%2Bclasses%2Band%2Bproperties%2Bdefinitions This snippet demonstrates how the 'edm:begin' property is used within an 'edm:TimeSpan' resource to specify a start date. It shows the RDF/XML syntax for associating a date with a time span. ```rdf 1964-10-12 ... ``` -------------------------------- ### edm:begin Example - BC Date Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106261527/edm%2BTimeSpan?atl_f=content-tree This example shows how to specify the start date of a timespan using the edm:begin property. Europeana recommends EDTF and ISO 8601 formats, but historical formats like '27 BC' are also shown. ```xml -0026 ``` ```xml 27 BC ``` -------------------------------- ### Example Entity Retrieval Request and Response (JSON-LD) Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2324561923/Entity%2BAPI%2BDocumentation Provides a concrete example of an HTTP GET request to retrieve metadata for an agent entity and its corresponding JSON-LD response. The response includes detailed information such as preferred labels, dates, associated places, and links to external data sources. ```http GET https://api.europeana.eu/entity/agent/base/147466 ``` ```json { "@context": "http://www.europeana.eu/schemas/context/entity.jsonld", "id": "http://data.europeana.eu/agent/147466", "type": "Agent", "isShownBy": { "id": "http://atena.beic.it/webclient/DeliveryManager?pid=8366128&custom_att_2=deeplink", "type": "WebResource", "source": "http://data.europeana.eu/item/9200369/webclient_DeliveryManager_pid_8365778_custom_att_2_simple_viewer", "thumbnail": "https://api.europeana.eu/api/v2/thumbnail-by-url.json?uri=http%3A%2F%2Fatena.beic.it%2Fwebclient%2FDeliveryManager%3Fpid%3D8366399%26custom_att_2%3Ddeeplink&type=SOUND" }, "prefLabel": { "de": "Arturo Toscanini", "fi": "Arturo Toscanini", "ru": "Артуро Тосканини", "sv": "Arturo Toscanini", "pt": "Arturo Toscanini", "bg": "Артуро Тосканини", "el": "Αρτούρο Τοσκανίνι", "en": "Arturo Toscanini", "hr": "Arturo Toscanini", "it": "Arturo Toscanini", "fr": "Arturo Toscanini", "hu": "Arturo Toscanini", "eu": "Arturo Toscanini", "sk": "Arturo Toscanini", "sl": "Arturo Toscanini", "ga": "Arturo Toscanini", "pl": "Arturo Toscanini", "ro": "Arturo Toscanini", "ca": "Arturo Toscanini", "nl": "Arturo Toscanini" }, "altLabel": { "ru": [ "Тосканини, Артуро" ] }, "dateOfBirth": "1867-03-25", "dateOfDeath": "1957-01-16", "placeOfBirth": "http://data.europeana.eu/place/148579", "note": { "de": [ "Italienischer Dirigent" ], "ru": [ "Итальянский дирижёр" ], "fi": [ "Italialainen kapellimestari" ], "sv": [ "Italiensk dirigent" ], "bg": [ "Италиански диригент" ], "el": [ "Ιταλός διευθυντής ορχήστρας" ], "en": [ "Italian conductor (1867-1957)" ], "it": [ "Direttore d'orchestra italiano (1867-1957)" ], "fr": [ "Chef d'orchestre italien" ], "pl": [ "Dyrygent włoski" ], "hu": [ "Olasz karmester" ], "nl": [ "Italiaans dirigent" ] }, "hasMet": [ "http://data.europeana.eu/concept/235" ], "sameAs": [ "http://www.wikidata.org/entity/Q13003", "http://viaf.org/viaf/19867298", "https://d-nb.info/gnd/118623443", "http://id.loc.gov/authorities/names/n50014549", "http://data.bnf.fr/ark:/12148/cb139005146", "http://www.idref.fr/027369293/id", "http://id.ndl.go.jp/auth/ndlna/00621569", "https://www.freebase.com/m/0140v2", "https://g.co/kg/m/0140v2", "http://openlibrary.org/works/OL5191079A", "http://libris.kb.se/resource/auth/313235", "http://datos.bne.es/resource/XX1282069", "http://data.bibliotheken.nl/id/thes/p072682442", "https://livedata.bibsys.no/authority/90606822", "http://id.worldcat.org/fast/4524", "http://data.cervantesvirtual.com/person/54819", "http://data.carnegiehall.org/names/10549", "https://libris.kb.se/mkz26r652wmwhm9", "http://dbpedia.org/resource/Arturo_Toscanini" ], "isAggregatedBy": { "id": "http://data.europeana.eu/agent/147466#aggregation", "type": "Aggregation", "created": "2023-01-20T14:56:39Z", "modified": "2023-01-20T14:56:39Z", "pageRank": 36, "recordCount": 0, "score": 658, "aggregates": [ "http://data.europeana.eu/agent/147466#aggr_europeana", "http://data.europeana.eu/agent/147466#aggr_source_1" ] } } ``` -------------------------------- ### edm:begin Example - Negative Year Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106261527 Provides an example of the edm:begin property, showing how to represent a start date in BC using a negative year format, recommended for EDTF and ISO 8601 compliance. ```xml -0026 ``` -------------------------------- ### Example Entity URI Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2324561923 Provides a concrete example of a URI for a specific entity, illustrating the syntax described previously. This URI can be used to access entity metadata. ```text http://data.europeana.eu/agent/59904 ``` -------------------------------- ### SKOS Concept Properties Examples Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106032167 Examples demonstrating the usage of various SKOS concept properties, including preferred labels, alternative labels, broader/narrower/related concepts, and matches from other schemes. These examples illustrate how to structure metadata for concepts. ```rdf Buccin Buccin Buccin ``` ```rdf Buccin ``` ```rdf ``` ```rdf ``` ```rdf ``` ```rdf ``` ```rdf ``` -------------------------------- ### Example Usage of edm:intermediateProvider Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106032160/ore%2BAggregation This example demonstrates how to represent the intermediate provider in a data supply chain scenario. It shows the relationship between dataProvider, provider, and intermediateProvider. ```xml Zuidwestbrabants Museum LoCloud Erfgoedplus.be ``` -------------------------------- ### Perform Direct HTTP GET Request for Content Negotiation Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2168848385/How%2Bto%2Bconfirm%2Bif%2Byour%2Bvocabulary%2Bsupports%2Bcontent%2Bnegotiation Demonstrates how to request a specific RDF/XML representation of a resource using the Accept header in an HTTP GET request. ```http GET http://viaf.org/viaf/110233335 HTTP/1.1 Accept: application/rdf+xml ``` -------------------------------- ### Install IIIF Server Components via Shell Script Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2355396609 This snippet demonstrates how to set execution permissions and run the automated installation script for Apache and IIPImage servers. It requires administrator privileges to configure system-level server settings. ```bash sudo chmod +x iiif-install.sh sudo ./iiif-install.sh ``` -------------------------------- ### GET /record/v2/search.json (Facets and Aggregation) Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2360508417/Europeana%2BAPI%2BFAQ Examples for data providers to analyze collections using facets for content tiers, metadata tiers, and dataset statistics. ```APIDOC ## GET /record/v2/search.json (Facets) ### Description Allows data providers to analyze collections by aggregating data based on specific facets such as contentTier, metadataTier, or dataset names. ### Method GET ### Endpoint /record/v2/search.json ### Parameters #### Query Parameters - **query** (string) - Required - The filter query (e.g., PROVIDER:"Name"). - **profile** (string) - Required - Set to 'facets' to enable aggregation. - **facet** (string) - Required - The field to aggregate by (e.g., contentTier, metadataTier). - **rows** (integer) - Required - Set to 0 to retrieve only facet counts without record data. ### Request Example https://api.europeana.eu/record/v2/search.json?query=PROVIDER:"Daguerreobase"&profile=facets&facet=DATA_PROVIDER&rows=0 ### Response #### Success Response (200) - **facets** (array) - Contains the aggregated counts for the requested fields. ``` -------------------------------- ### Example Manifest for Video (v2) Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2398912540 Demonstrates the manifest structure for a video resource in v2, falling under 'Browser Supported' MIME types. The video resource is included as a painting-type annotation on a canvas. ```json { "@context": "http://iiif.io/api/presentation/2.1/context.json", "@id": "http://example.com/manifest/video-v2", "@type": "sc:Manifest", "sequences": [ { "@type": "sc:Sequence", "canvases": [ { "@type": "sc:Canvas", "@id": "http://example.com/canvas/video-v2", "width": 1920, "height": 1080, "images": [ { "@type": "oa:Annotation", "motivation": "sc:painting", "resource": { "@id": "http://example.com/webresource/video.mp4", "@type": "dctypes:MovingImage", "format": "video/mp4" }, "on": "http://example.com/canvas/video-v2" } ] } ] } ] } ``` -------------------------------- ### Include Direct Media Representation with Embeddable Resource (RDF/XML) Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2820177937/Embeddable%2Bresources%2Bin%2BEDM%2Bguidelines This example demonstrates how to provide a direct media representation (e.g., a JPEG) alongside an embeddable resource. The relationship is established using 'dcterms:isFormatOf', ensuring the URLs match precisely. The embeddable resource itself follows the same principles as outlined for providing thumbnails. ```xml [...] [...] [...] Flickr ``` -------------------------------- ### Direct Approach: GET Request with Accept Header Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2168848385/How%2Bto%2Bconfirm%2Bif%2Byour%2Bvocabulary%2Bsupports%2Bcontent%2Bnegotiation Demonstrates how a user agent can request a specific representation (RDF/XML) of a resource by sending an 'Accept' header with an HTTP GET request. ```APIDOC ## GET /viaf/{id} with Accept Header ### Description Requests a specific representation (e.g., RDF/XML) of a resource using the Accept HTTP header. ### Method GET ### Endpoint `http://viaf.org/viaf/{id}` ### Parameters #### Query Parameters None #### Headers - **Accept** (string) - Required - The media type(s) the user agent prefers (e.g., `application/rdf+xml`). ### Request Example ```http GET http://viaf.org/viaf/110233335 HTTP/1.1 Accept: application/rdf+xml ``` ### Response #### Success Response (200) - **Content-Type** (string) - The media type of the returned resource (e.g., `application/rdf+xml; charset=UTF-8`). - **Body** (XML) - The RDF/XML representation of the resource. #### Response Example ```http HTTP/1.x 200 OK Content-Type: application/rdf+xml; charset=UTF-8 ... remaining XML content ... ``` ``` -------------------------------- ### Example Manifest for Video (v2) - Specialised Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2398912540 Illustrates a v2 manifest for a video resource under 'Specialised' MIME types. It includes thumbnails and the video resource as a rendering component, excluding it from painting annotations. ```json { "@context": "http://iiif.io/api/presentation/2.1/context.json", "@id": "http://example.com/manifest/video-v2-specialised", "@type": "sc:Manifest", "sequences": [ { "@type": "sc:Sequence", "canvases": [ { "@type": "sc:Canvas", "@id": "http://example.com/canvas/video-v2-specialised", "width": 640, "height": 480, "images": [ { "@type": "oa:Annotation", "motivation": "sc:painting", "resource": { "@id": "http://example.com/thumbnail/video.jpg", "@type": "dctypes:Image", "format": "image/jpeg" }, "on": "http://example.com/canvas/video-v2-specialised" } ], "rendering": { "@id": "http://example.com/webresource/video.mp4", "@type": "video/mp4", "label": "Actual Video Resource" } } ] } ] } ``` -------------------------------- ### skos:note Example Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106261527/edm%2BTimeSpan?atl_f=content-tree This example illustrates the use of skos:note to provide additional descriptive information about the timespan, such as its historical context and characteristics. ```xml The Roman Empire (Latin: Imperium Romanum) was the post-Republican period of the ancient Roman civilization, characterised by an autocratic form of government and large territorial holdings around the Mediterranean in Europe, Africa, and Asia. ``` -------------------------------- ### wgs84_pos:alt - Altitude Property Example Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2105901079/edm%2BPlace Example of the wgs84_pos:alt property, which specifies the altitude of a spatial thing in decimal meters above the reference. ```xml 21 ``` -------------------------------- ### dc:contributor RDF Example Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106294284 Example of how to specify a contributor to the cultural heritage object (CHO). It can be a literal value or a reference to an Agent class instance. ```rdf Maria Callas or create a reference to an instance of the Agent class ``` -------------------------------- ### skos:notation Example - EDTF Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106261527/edm%2BTimeSpan?atl_f=content-tree This example demonstrates how to use skos:notation to represent a timespan using a specific notation, such as the EDTF format for dates. ```xml ../-5300 ``` -------------------------------- ### Search API - Pagination with Rows and Start Parameters Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2360508417/Europeana%2BAPI%2BFAQ Control the number of results and pagination for Search API queries using 'rows' and 'start' parameters. ```APIDOC ## GET /record/v2/search.json ### Description Allows control over the number of search results returned and the starting point for pagination. The `rows` parameter specifies the number of results per page (max 100), and the `start` parameter specifies the index of the first result to retrieve. ### Method GET ### Endpoint https://api.europeana.eu/record/v2/search.json ### Parameters #### Query Parameters - **query** (string) - Required - The search query. - **rows** (integer) - Optional - The number of results to return per page. Defaults to 12. Maximum value is 100. - **start** (integer) - Optional - The index of the first search result to retrieve. Used for pagination. ### Request Example ```json { "example": "https://api.europeana.eu/record/v2/search.json?query=who:(Leonardo%20da%20Vinci)&rows=100&start=201" } ``` ### Response #### Success Response (200) - **response** (JSON) - A list of search results, paginated according to the `rows` and `start` parameters. #### Response Example ```json { "example": "https://api.europeana.eu/record/v2/search.json?query=who:(Leonardo%20da%20Vinci)&rows=100&start=201" } ``` ``` -------------------------------- ### Entity URI Syntax Example Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2324561923 Demonstrates the standard URI syntax for identifying Europeana entities. This format is used across the API for content negotiation. ```text http://data.europeana.eu/[ENTITY_TYPE]/[ENTITY_ID] ``` -------------------------------- ### dc:creator RDF Example Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106294284 Example of specifying the creator of the CHO. It can be a literal value or a reference to an Agent class instance, preferably with an identifier from an authority source. ```rdf Shakespeare, William or create a reference to an instance of the Agent class ``` -------------------------------- ### Example Manifest for Video (v3) - Specialised Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2398912540 Details a v3 manifest for a video resource under 'Specialised' MIME types. Includes thumbnail annotations and the video as a rendering component, with video excluded from painting. ```json { "@context": "http://iiif.io/api/presentation/3.0/context.json", "id": "http://example.com/manifest/video-v3-specialised", "type": "Manifest", "items": [ { "id": "http://example.com/canvas/video-v3-specialised", "type": "Canvas", "width": 640, "height": 480, "items": [ { "id": "http://example.com/annotation/video-v3-specialised", "type": "Annotation", "motivation": "painting", "body": { "id": "http://example.com/thumbnail/video.jpg", "type": "Image", "format": "image/jpeg" }, "target": "http://example.com/canvas/video-v3-specialised" } ], "rendering": [ { "id": "http://example.com/webresource/video.mp4", "type": "Video", "format": "video/mp4", "label": "Actual Video Resource" } ] } ] } ``` -------------------------------- ### Example: dcterms:conformsTo Property for edm:WebResource Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106392591/edm%2BWebResource Indicates an established standard to which the web resource conforms. An example is the Web Content Accessibility Guidelines (WCAG). ```xml W3C WCAG 2.0 ``` -------------------------------- ### Example API Request for Rich Profile Search Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2385739812/Search%2BAPI%2BDocumentation This example demonstrates how to request the broadest set of metadata in a search response by using the 'rich_' profile. It queries for 'Paris' and expects a JSON output. ```HTTP https://api.europeana.eu/record/v2/search.json?query=Paris &profile=rich_ ``` -------------------------------- ### SKOS Concept - Related Relationship Example Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106032167/skos%2BConcept Provides an example of the skos:related property, which links to a related concept in the same thesaurus or controlled vocabulary. This is an optional property. ```rdf ``` -------------------------------- ### Search API - Pagination Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2360508417/API%2BFAQ Demonstrates how to use the 'rows' and 'start' parameters to paginate through search results. ```APIDOC ## GET /record/v2/search.json with Pagination ### Description Controls the number of search results returned and the starting point for subsequent requests to retrieve all matching items. ### Method GET ### Endpoint https://api.europeana.eu/record/v2/search.json ### Parameters #### Query Parameters - **query** (string) - Required - The search query. - **rows** (integer) - Optional - Specifies the number of results to return per page. Default is 12, maximum is 100. - **start** (integer) - Optional - Specifies the index of the first search result to return. Used to skip a certain number of results for pagination. ### Request Example ```json { "example": "https://api.europeana.eu/record/v2/search.json?query=who:(Leonardo%20da%20Vinci)&rows=100" } ``` ### Pagination Examples - To get the first 100 results: `https://api.europeana.eu/record/v2/search.json?query=who:(Leonardo%20da%20Vinci)&rows=100` - To get the next 100 results (results 101-200): `https://api.europeana.eu/record/v2/search.json?query=who:(Leonardo%20da%20Vinci)&rows=100&start=101` - To get results 201-300: `https://api.europeana.eu/record/v2/search.json?query=who:(Leonardo%20da%20Vinci)&rows=100&start=201` ``` -------------------------------- ### dcterms:isPartOf - Is Part Of Relationship Example Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2105901079/edm%2BPlace Example of the dcterms:isPartOf property, which links to a place that the described place is a part of. It uses an RDF resource reference. ```xml ``` -------------------------------- ### dcterms:hasPart - Has Part Relationship Example Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2105901079/edm%2BPlace Example of the dcterms:hasPart property, which links to a place that is a part of the described place. It uses an RDF resource reference. ```xml ``` -------------------------------- ### SKOS Concept - Match Properties Examples Source: https://europeana.atlassian.net/wiki/spaces/EF/pages/2106032167/skos%2BConcept Illustrates the usage of various match properties (broadMatch, narrowMatch, relatedMatch, exactMatch, closeMatch) for linking concepts across different concept schemes. These are optional properties. ```rdf ```