The library's API
The Koldo Mitxelena library makes the information in its catalog available through a REST-style API (Application Programming Interface), so you can use it and integrate it into your own site. This document describes the functionality exposed by the API, and is meant as a guide for bloggers, webmasters or programmers who might use these access tools to enrich web sites and use the information in the library catalog in useful and creative ways.
The term book is used in this document to mean "resource listed in the catalog", it could be a real book, a CD, a poster, a photograph, or any othe the objects, physical or digital, that a library might hold.
Accessing a Book Record in the Catalog
Get the record for a book:
URL: http://liburutegia.gipuzkoa.net/api/rest/1.0/book/reference.xml
HTTP method: GET
Result: Record for the book, in Dublin Core format.
XML Example
curl http://liburutegia.gipuzkoa.net/api/rest/1.0/book/000000594191.xml
<?xml version="1.0" encoding="utf-8" ?> <book xmlns:dc="http://purl.org/dc/elements/1.1/"> <dc:identifier>(KM)AMICUS:000000594191</dc:identifier> <dc:identifier>ISBN:978-84-8152-360-7</dc:identifier> <dc:identifier>CDU:913 ESP</dc:identifier> <dc:title>Guía oficial de campings de España</dc:title> <dc:description>Tít. tomado de la cub Índices </dc:description> <dc:type>book</dc:type> <dc:coverage type="spatial">España</dc:coverage> <dc:language>eng</dc:language> <dc:language>eng</dc:language> <dc:language>fre</dc:language> <dc:language>ger</dc:language> <dc:format>526 p., [2] p. de mapas mapas 24 cm +</dc:format> <dc:publisher>[Madrid]. Turespaña</dc:publisher> <library_urls> <url name="Koldo Mitxelena"> <![CDATA[ http://www4.gipuzkoa.net/KMKatalogoa/default.aspx?hreciid=|library%2Fmarc%2Famicus|000000594191 ]]> </url> </library_urls> <dc:rights></dc:rights> <dc:source></dc:source> <dc:date>2009</dc:date> <dc:relation type="marc:777">Guía oficial de campings de España. (KM)594192</dc:relation> <dc:relation type="marc:777">Mapa de campings y carreteras de España]. (KM)594533</dc:relation> <dc:subject type="marc:650">Camping</dc:subject> </book>
Search
Returns the list of records in the catalog that match the search criteria specified.
URL: http://liburutegia.gipuzkoa.net/api/rest/1.0/books.format where format is one of xml, rss, js, json, html.
HTTP method: GET
Parameters:
-
q: Optional. Text query parameter.
Example: http://liburutegia.gipuzkoa.net/api/rest/1.0/books.xml?q=fundacion - author: Optional. Name of the author.
- title: Optional. Title of the book.
- isbn: Optional. ISBN for the book
-
keywords: Optional. Subject matter of the book.
Example: http://liburutegia.gipuzkoa.net/api/rest/1.0/books.xml?keywords=beasain
Result: A list of the records found in the catalog.
XML Example
curl "http://liburutegia.gipuzkoa.net/api/rest/1.0/books.xml?q=fundacion"
<?xml version="1.0" encoding="utf-8" ?> <books> <book> <reference>000000432888</reference> <title>Aena</title> <subtitle>Arte garaikideko bilduma : [Artearen Kutxaguneko Kubo Aretoan] = Colección de arte contemporáneo : [Sala Kubo-Kutxaespacio del Arte]</subtitle> <authors> <author>Fundación Kutxa</author> </authors> <summary>Textos en euskera, castellano, francés e inglés</summary> <cdu>7</cdu> <year>2002</year> <series>Colección Kubo-Kutxa ;</series> <subject> <keyword>arte</keyword> <keyword>exposiciones</keyword> <keyword>fundación aena</keyword> <keyword>s. xx</keyword> <keyword>colecciones de arte</keyword> <keyword>exposiciones</keyword> </subject> <terms_found> <keyword score="4">fundación</keyword> </terms_found> </book> </books>
Returned Records
Record listing
A list or array filled with objects with the following attributes:
-
reference: Identifier for the book
- In the example: 000000432888
-
title
- In the example: Aena
-
subtitle
- In the example: Arte garaikideko bilduma : [Artearen Kutxaguneko Kubo Aretoan] = Colección de arte contemporáneo : [Sala Kubo-Kutxaespacio del Arte]
-
authors
- In the example: Fundación Kutxa
-
summary: A summary or description of the book.
- In the example: Textos en euskera, castellano, francés e inglés
-
CDU: Library call number for the book.
- In the example: 7.036 FUN AEN
-
year: Publication year.
- In the example: 2002
-
series: Series to which the book belongs.
- In the example: Colección Kubo-Kutxa
-
subject: Keyword list for the subject matter of the book.
- In the example: arte, exposiciones, fundación aena,s. xx, colecciones de arte, exposiciones
-
terms_found: Listing of the search terms that matched.
- In the example: fundación (4 matches in the record)
HTTP Status Codes
The API is designed to return the appropriate HTTP status code for the requests it receives.
- 200 OK : The request was processed successfully.
- 404 Not Found : No matching book was found.
- 500 Internal Server Error : An internal error has occurred within the software that implements the API. Please let us know the context in which you encounter this (if ever!), so we can investigate.
- 503 Service Unavailable : Our servers cannot handle your request at this time (downtime, overload, etc.).
Examples
The following examples illustrate the use of the API: