0.0
No commit activity in last 3 years
No release in over 3 years
Search and retrieve records from the Europeana REST API
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

~> 1.3
>= 0
>= 0
~> 3.0
~> 1.18.0

Runtime

>= 4.2, < 6.0
~> 0.9, < 0.12.2
~> 0.2.5
> 1.6.2
~> 1.1
 Project Readme

Europeana API

Build Status Security Maintainability Test Coverage

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.

Sign up for an API key at: https://pro.europeana.eu/get-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 v1.2.

For full details, see LICENSE.md.