News

The library catalog data of the Vaski libraries has been released as open data.

The data can be found at the raw data section of this site.

Read the press release (in Finnish)

What

This API exposes HelMet Library data and provides search results in JSON and MarcXML format.

Currently the API is read-only.

How

At the moment you can perform searches by: author, title or isbn.

Depending on the format you want the search result to be in, you can change the file extension in the url to either json or marcxml. To get JSON results with JSONP, define callback function and add &callback=[callback function name] to the request string.

By author:

Example url

http://data.kirjastot.fi/search/author.json?query=Campbell
OR
http://data.kirjastot.fi/search/author.marcxml?query=Campbell

By title:

Example url

http://data.kirjastot.fi/search/title.json?query=raportti
OR
http://data.kirjastot.fi/search/title.marcxml?query=raportti

By ISBN:

Example url

http://data.kirjastot.fi/search/isbn.json?query=6420614617953
OR
http://data.kirjastot.fi/search/isbn.marcxml?query=6420614617953

Output

Depending on the format you requested in the url you can get:

JSON

Output example

{
 "author": "Oksanen, Sofi", 
 "author_details": [], 
 "contents": [], 
 "description": [
 "Perustuu tekij\u00e4n samannimiseen n\u00e4ytelm\u00e4\u00e4n"
 ], 
 "extent": [
 "380 s. ;"
 ], 
 "isbn": "9789510339732", 
 "library_id": "(FI-HELMET)b1854574", 
 "library_url": "http://www.helmet.fi/record=b1854574~S9*eng", 
 "title": "Puhdistus : romaani", 
 "type": "book"
 }

MARCXML

Output example

<?xml version="1.0" encoding="UTF-8"?> 
<collection xmlns="http://www.loc.gov/MARC21/slim"> 
   <record> 
  <leader>00485nam  2200169   4500</leader> 
  <controlfield tag="001">kr2043314X</controlfield> 
  <controlfield tag="005">20021115010101.0</controlfield> 
  <controlfield tag="008">000905s1979    xx                  fin  </controlfield> 
  <datafield tag="035" ind1=" " ind2=" "> 
   <subfield code="a">(FI-HELMET)b1000002</subfield> 
  </datafield> 
  <datafield tag="041" ind1="0" ind2=" "> 
   <subfield code="a">fin</subfield> 
  </datafield> 
  <datafield tag="110" ind1="1" ind2=" "> 
   <subfield code="a">Helsingin kaupunki.</subfield> 
   <subfield code="b">Lasten päivähoitovirasto</subfield> 
  </datafield> 
  <datafield tag="245" ind1="1" ind2="0"> 
   <subfield code="a">0-3 -vuotiaiden kehittämistyöryhmän raportti 1 :</subfield> 
   <subfield code="b">liite 1: välineistö ja materiaali</subfield> 
  </datafield> 
  <datafield tag="260" ind1=" " ind2=" "> 
   <subfield code="a">Helsinki,</subfield> 
   <subfield code="c">1979</subfield> 
  </datafield> 
  <datafield tag="300" ind1=" " ind2=" "> 
   <subfield code="a">[16 s.] :</subfield> 
   <subfield code="b">nid.</subfield> 
  </datafield> 
  <datafield tag="546" ind1=" " ind2=" "> 
   <subfield code="a">suomi</subfield> 
  </datafield> 
  <datafield tag="588" ind1=" " ind2=" "> 
   <subfield code="a">180.2</subfield> 
  </datafield> 
  <datafield tag="599" ind1=" " ind2=" "> 
   <subfield code="a">KIRJA / BOK</subfield> 
  </datafield> 
  <datafield tag="913" ind1="0" ind2="0"> 
   <subfield code="a">*03VKR199000</subfield> 
  </datafield> 
 </record> 
</collection>

Pagination for JSON and MARCXML format

JSON

{
  "current_page":1,
  "per_page":5,
  "total_entries":0,
  "entries":[]
}

Every search result in json format will start always like in the example above.

If the number of total_entries is bigger that the per_page attribute, you can change the current_page by adding to the end of the url &page=[the number of the page you wish to view] like in the example below:
http://data.kirjastot.fi/search/title.json?query=ja&page=2

MARCXML

Changing the parameter page the same way you would do for JSON format will give you the page you requested.

Examples

JSONP

You should probably use a JavaScript library to handle JSONP. Here is an example using jQuery -library.

$.getJSON('http://data.kirjastot.fi/search/title.json?query=ja&callback=?', function(data) {
  // Define your own processing of the JSON...
  process(data);
});

JSON client with Ruby

This example shows searching records by title and returning a parsed Ruby object. All needed libraries are included in the Ruby Standard Library.

require "net/http"
require "json"

class Helmet
  def self.search_by_title(title)
    request = Net::HTTP::Get.new("/search/title.json?query=#{CGI.escape(title)}")
    http = Net::HTTP.new("data.kirjastot.fi")
    response = http.start { |http| http.request(request) }
    
    if response.class.superclass == Net::HTTPSuccess
      return JSON.parse(response.body)
    else
      raise "HTTP request failed: #{response.code}"
    end
  end
end

Helmet.search_by_title("ja") # Returns Ruby hash generated from the JSON