api json dell'opac SBN

Alcuni mesi fa è stata rilasciata da ICCU una app mobile per consultare l'OPAC SBN. Anche se graficamente poco accattivante l'app funziona bene, e trovo molto utili le funzioni di ricerca di un libro scansionando il codice a barre con la camera del telefonino, e la possibilità di bookmarkare dei preferiti.
Incuriosito dal funzionamento ho pensato di analizzarne il traffico http.

screenshot

Con mitmproxy in esecuzione sul laptop ho settato il device android

Settings > Wi-Fi > Modify Network > Show advanced options > Proxy: Manual

configurando Proxy hostname e Proxy port con l'indirizzo del laptop nella mia rete e la porta :8080

Effettuando delle operazioni di ricerca con la app ho potuto ispezionarne il traffico http, vedendo del traffico di dati json verso l'endpoint http://opac.sbn.it/opacmobilegw

mitmproxy

Qui alcune delle API principali:

Ricerca libera

URL: http://opac.sbn.it/opacmobilegw/search.json?any={STRING}&type=0&start=0&rows=3

Ricerca una {STRING} nell'intero catalogo (paginando i risultati con i parametri start e row), avendo come risposta una serie di record nel seguente formato (oltre ad altre informazioni interessanti, come faccette e soggetti).

{
    "autorePrincipale": "Comici, Emilio",
    "citazioni": [],
    "codiceIdentificativo": "IT\\ICCU\\RAV\\2002745",
    "livello": "Monografia",
    "localizzazioni": [],
    "luogoNormalizzato": [],
    "nomi": [],
    "note": [],
    "numeri": [],
    "progressivoId": 0,
    "pubblicazione": "Milano : Corriere Della Sera, 2014",
    "tipo": "Testo a stampa",
    "titolo": "Alpinismo eroico / Emilio Comici"
}

Ricerca per ISBN

URL: http://opac.sbn.it/opacmobilegw/search.json?isbn={ISBN}

Esempio: /search.json?isbn=9788842092995

Metadati di un singolo record (BID)

URL: http://opac.sbn.it/opacmobilegw/full.json?bid={BID}

Effettuando la chiamata con un BID (dalla risposta precedente "codiceIdentificativo": "IT\\ICCU\\RAV\\2002745" - nota: i backslash sono singoli) si ottiene un record json con i metadati del libro, corredati delle localizzazioni (le biblioteche che lo possiedono) complete di coordinate geografiche (quindi pronte per essere visualizzate su una mappa).

esempio: /full.json?bid=IT\ICCU\RAV\2002745

Risposta ottenuta:

{
    "autorePrincipale": "Comici, Emilio",
    "citazioni": [
        {
            "standard": "mla",
            "valore": "Comici, Emilio. Alpinismo eroico Milano Corriere Della Sera, 2014"
        },
        {
            "standard": "apa",
            "valore": "Comici, E. (2014). Alpinismo eroico Milano Corriere Della Sera."
        }
    ],
    "codiceIdentificativo": "IT\\ICCU\\RAV\\2002745",
    "collezione": "Biblioteca della montagna ; 8",
    "descrizioneFisica": "170 p. ; 19 cm",
    "linguaPubblicazione": "ITALIANO",
    "livello": "Monografia",
    "localizzazioni": [
        {
            "comune": "Canale d'Agordo",
            "denominazione": "BIBLIOTECA COMUNALE DI CANALE D'AGORDO",
            "isil": "IT-BL0089",
            "latitudine": 46.3606418,
            "longitudine": 11.9148422,
            "provincia": "BL",
            "sbn": "VIACQ"
        },
        {
            "comune": "Associazione Italiana Cultura Sport",
            "denominazione": "Biblioteca del Centro Informazione Documentazione",
            "isil": "IT-BO0630",
            "latitudine": 44.4769143,
            "longitudine": 11.4094361,
            "provincia": "CID-AICS",
            "sbn": "UBOXA"
        },
        {
            "comune": "Firenze",
            "denominazione": "Biblioteca delle Oblate",
            "isil": "IT-FI0104",
            "latitudine": 43.772209,
            "longitudine": 11.2600206,
            "provincia": "FI",
            "sbn": "RT1AA"
        },
        {
            "comune": "Latina",
            "denominazione": "Biblioteca comunale Aldo Manuzio",
            "isil": "IT-LT0048",
            "latitudine": 41.4675967,
            "longitudine": 12.9037,
            "provincia": "LT",
            "sbn": "RMSA2"
        },
        {
            "comune": "Milano",
            "denominazione": "Biblioteca nazionale Braidense",
            "isil": "IT-MI0185",
            "latitudine": 45.471946,
            "longitudine": 9.187845,
            "provincia": "MI",
            "sbn": "MILNB"
        },
        {
            "comune": "Rimini",
            "denominazione": "Biblioteca civica Gambalunga",
            "isil": "IT-RN0013",
            "latitudine": 44.0616558,
            "longitudine": 12.5678351,
            "provincia": "RN",
            "sbn": "RAVRI"
        },
        {
            "comune": "Pecetto Torinese",
            "denominazione": "Biblioteca civica",
            "isil": "IT-TO0152",
            "latitudine": 45.0170177,
            "longitudine": 7.7491581,
            "provincia": "TO",
            "sbn": "TO13T"
        },
        {
            "comune": "Trieste",
            "denominazione": "Biblioteca comunale Stelio Mattioni",
            "isil": "IT-TS0268",
            "latitudine": 45.6164974,
            "longitudine": 13.8230741,
            "provincia": "TS",
            "sbn": "TSAU2"
        },
        {
            "comune": "Iesolo",
            "denominazione": "BIBLIOTECA CIVICA DI JESOLO",
            "isil": "IT-VE0124",
            "latitudine": 45.5367875,
            "longitudine": 12.6391389,
            "provincia": "VE",
            "sbn": "VIAVJ"
        }
    ],
    "luogoNormalizzato": [],
    "nomi": [
        "Comici, Emilio"
    ],
    "note": [
        "Edizione speciale per Corriere della Sera."
    ],
    "numeri": [],
    "paesePubblicazione": "ITALIA",
    "pubblicazione": "Milano : Corriere Della Sera, 2014",
    "tipo": "Testo a stampa",
    "titolo": "Alpinismo eroico / Emilio Comici"
}

Disclaimer

Queste API non sono documentate pubblicamente, per cui potrebbero cambiare. E non sono noti nemmeno i termini di utilizzo, per cui non sono certo che si possano usare liberamente per costruirci sopra applicazioni esterne. Se volete sperimentarle in ogni caso evitate operazioni di scraping selvaggio, ed esprimete con una mail all'ICCU il desiderio di vedere questo tipo di servizi resi pubblici, documentati, con opportune licenze d'uso aperte.