Europeana API

Ruby client library for the search and retrieval of records from the Europeana REST APIs.

Requirements

Ruby >= 2.3

Installation

Add this line to your application's Gemfile:

gem 'europeana-api'

And then execute:

bundle

Or install it yourself as:

gem install europeana-api

Usage

Authentication

Authentication by API key is required for all requests to the Europeana API.

Configure your application with the API key:

require 'europeana/api'
Europeana::API.key = 'xyz'

Response format

Responses from the API methods described below will by default be hashes with indifferent access, i.e. values can be retrieved by string or symbol keys.

To have API methods return objects instead:

Europeana::API.configure do |config|
  config.parse_json_to = OpenStruct
end

Records

Search

search = Europeana::API.record.search(query: '"first world war"')
search[:items] # => [ item1, item2, ... ]
search[:totalResults] # => 81530

See https://pro.europeana.eu/resources/apis/search for details of the available request parameters, and of the data returned in the search response.

Fetch

record = Europeana::API.record.fetch(id: '/92070/BibliographicResource_1000126223918')
record[:object][:title] # => ["Panorama des Schafberges in Ober-Österreich. Blatt 1"]
record[:object][:proxies].first[:dcCreator][:def] # => ["Simony, Friedrich"]

See https://pro.europeana.eu/resources/apis/record for details of the data returned in the record response.

Hierarchies

hierarchy = Europeana::API.record.parent(id: '/2048604/data_item_onb_abo__2BZ17084070X')
hierarchy[:parent][:id] # => "/2048604/data_item_onb_abo_AC10352829"

Methods available for hierarchy retrieval:

Europeana::API.record.self
Europeana::API.record.parent
Europeana::API.record.children
Europeana::API.record.preceding_siblings
Europeana::API.record.following_siblings
Europeana::API.record.ancestor_self_siblings

Annotations

See https://pro.europeana.eu/resources/apis/annotations for details of the responses received from the Annotations API methods.

Search

search = Europeana::API.annotation.search(query: 'music')
search[:items].first # => "http://data.europeana.eu/annotation/collections/8"

Fetch

annotation = Europeana::API.annotation.fetch(provider: 'collections', id: 8)
annotation[:body] # => "Sheet music"

Create

body = { bodyValue: 'Trombones', motivation: 'tagging', target: 'http://data.europeana.eu/item/09102/_UEDIN_214' }
annotation = Europeana::API.annotation.create(userToken: 'secret-token', body: body.to_json)
annotation[:id] # => "http://www.europeana.eu/api/annotations/myname/1234"

Update

body = { bodyValue: 'Trombones', motivation: 'tagging' }
annotation = Europeana::API.annotation.update(provider: 'myname', id: '1234', userToken: 'secret-token', body: body.to_json)
annotation[:body][:value] # => "Trombones"

Delete

Europeana::API.annotation.delete(provider: 'myname', id: '1234', userToken: 'secret-token') # => ""

License

Licensed under the EUPL V.1.1.

For full details, see LICENSE.md.