Introduction

Overview

Nasjonalbibliotekets search API provides search possibilities in metadata and content for client applicatons. The search API is based on open standards and protocols like HTTP, XML, Atom feed and OpenSearch.

A search in Nasjonalbibliotekets Search API is done by sending an HTTP GET request. The result of a search is returned in Atom format enriched with OpenSearch elements.

Target audience

This document is meant for programmers wanting to develop client applications querying Nasjonalbibliotekets search services.

Search

Opensearch Description Document

The Opensearch Description Document (ODD) defines what parameters that can be given to the API. The ODD of Nasjonabibliotekets Search Service:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:nb="http://www.nb.no/xml/search/1.0/">
  <ShortName>NBSearch</ShortName>
  <Description>Nasjonalbibliotekets general Search API for client applications</Description>
  <Tags>søk</Tags>
  <Contact>search@nb.no</Contact>
  <Url type="application/atom+xml" template="http://www.nb.no/services/search/v2/search?q={searchTerms}&startIndex={startIndex?}&itemsPerPage={count?}&facet={nb:facetSpec?}&fq={nb:facetQuery?}&filter={nb:filterQuery?}&sort={nb:sort?}&qp={nb:queryProfile?}&ft={nb:ft}"/>
  <LongName>Nasjonalbiblioteket search</LongName>
  <Query count="1" searchTerms="Ibsen" role="example"/>
  <Developer>Nasjonalbibliotekets Development Team</Developer>
  <Language>no-NO</Language>
  <OutputEncoding>UTF-8</OutputEncoding>
  <InputEncoding>UTF-8</InputEncoding>
</OpenSearchDescription>

Request

A simple search request: http://www.nb.no/services/search/v2/search?q=provenykonsekvenser&itemsPerPage=2

Response

Example of a response from the search API:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:ns2="http://a9.com/-/spec/opensearch/1.1/" xmlns:ns3="http://www.w3.org/1999/xhtml">
  <id>http://www.nb.no/atomfeed</id>
  <updated>2011-05-20T11:02:03.104+02:00</updated>
  <title type="text">NBSearch</title>
  <subtitle type="text">Nasjonalbibliotekets general Search API for client applications, results: 1 - 2 of 2</subtitle>
  <ns2:itemsPerPage>2</ns2:itemsPerPage>
  <ns2:startIndex>1</ns2:startIndex>
  <ns2:totalResults>2</ns2:totalResults>
  <ns2:Query startIndex="1" searchTerms="provenykonsekvenser" role="request"/>
  <link href="http://www.nb.no/services/search/v2/search?q=provenykonsekvenser&amp;itemsPerPage=2" rel="self"/>
  <link href="http://www.nb.no/services/search/v2/search?alt=application/opensearchdescription+xml" type="application/opensearchdescription+xml" rel="search"/>
  <entry>
    <id>http://www.nb.no/services/search/v2/search/7b4b476076670508446fd5508cf601e9</id>
    <title type="text">En analyse av noen alternative endringer i petroleumsskattesystemet : provenykonsekvenser og incentivegenskaper</title>
    <summary type="text">av Gunnar Stensland, Kjell Sunnevåg SNF-prosjekt nr. 3880: "Analyse av petroleumsskattesystemet - konsekvenser ved endringer i en eller flere parametre"</summary>
    <link href="http://www.nb.no/services/search/v2/mods/1522203" type="text/xml" rel="via" title="MODS metadata"/>
    <link href="http://www.nb.no/services/search/v2/holdings/1522203" type="text/xml" rel="related" title="Holdings"/>
    <link href="http://urn.nb.no/URN:NBN:no-nb_digibok_2009073101107" type="text/html" rel="related" title="Object"/>
    <nb:digital xmlns:nb="http://www.nb.no/xml/search/1.0/">true</nb:digital>
    <nb:mainentry xmlns:nb="http://www.nb.no/xml/search/1.0/">Analyse av Petroleumsskattesystemet - Konsekvenser Ved Endringer I. En Eller Flere Parametre(prosjekt); Stensland, Gunnar; Sunnevåg, Kjell</nb:mainentry>
    <nb:mediatype xmlns:nb="http://www.nb.no/xml/search/1.0/">Bøker</nb:mediatype>
    <nb:year xmlns:nb="http://www.nb.no/xml/search/1.0/">1995</nb:year>
    <nb:date xmlns:nb="http://www.nb.no/xml/search/1.0/">1995-01-01</nb:date>
  </entry>
  <entry>
    <id>http://www.nb.no/services/search/v2/search/093fa5e59a7ea4139ba88a29081b32b3</id>
    <title type="text">Skattlegging av petroleumsvirksomhet : innstilling fra et utvalg oppnevnt ved kongelig resolusjon 22. oktober 1999 : avgitt til Finansdepartementet 20. juni 2000</title>
    <summary type="text">Utvalgets navn: Petroleumsskatteutvalget. Leder: Nina Bjerkedal Elektronisk reproduksjon</summary>
    <link href="http://www.nb.no/services/search/v2/mods/3002126" type="text/xml" rel="via" title="MODS metadata"/>
    <link href="http://www.nb.no/services/search/v2/holdings/3002126" type="text/xml" rel="related" title="Holdings"/>
    <link href="http://urn.nb.no/URN:NBN:no-nb_digibok_2009073101107" type="text/html" rel="related" title="Object"/>
    <nb:digital xmlns:nb="http://www.nb.no/xml/search/1.0/">true</nb:digital>
    <nb:mainentry xmlns:nb="http://www.nb.no/xml/search/1.0/">Finansdepartementet; Petroleumsskatteutvalget; Bjerkedal, Nina</nb:mainentry>
    <nb:mediatype xmlns:nb="http://www.nb.no/xml/search/1.0/">Bøker</nb:mediatype>
    <nb:year xmlns:nb="http://www.nb.no/xml/search/1.0/">2000</nb:year>
    <nb:date xmlns:nb="http://www.nb.no/xml/search/1.0/">2000-01-01</nb:date>
  </entry>
</feed>

Query Syntax

This chapter describes the query syntax for Nasjonalbibliotekets search API.

Terms

A query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases. A Single Term is a single word such as kake or banan. A Phrase is a group of words surrounded by double quotes such as "hallo i luken". Multiple terms can be combined together with operators to form a more complex query (see below).

Wildcard searches

The API support prefix wildcard terms, matching all words starting with the given text. Example: superma* will match all terms that start with superma, e.g. superman and supermad

Range searches

Syntax : <fieldname>:[<lowerLimit> TO <upperLimit>]

The result set returned will contain documents with fieldname values within the span specified (including the upper and lower limit).

Examples:

Range query is currently supported only for the date field.

Field queries

It is possible to limit the query to specific parts of the indexed content using a prefix in front of the query term. For instance using the query title:pan will search for the term pan only in the title field. When not using field searches the default behavior wil be to query all of the following fields at the same time:

Field NameDescription
titleThe title of the resource
namecreatorName of the creator of the intellectual content of the resource (main entry)
descriptionInformation about the contents of a resource
subjectContainer field for other subject fields (see below)
otherid-
isbnISBN, International Standard Book Number
series-

To query the freetext field in addition to the default metadata fields use: &ft=true.

All the above fields may be used in field queries. In addition the following fields may be used:

Field NameDescriptionRange Search
dateFormat: YYYYMMDDYes
yearFormat: YYYYYes
monthFormat: MMYes
dayFormat: DDYes
subjectnameName as subject-
subjectgeographicGeographic subject terms-
subjecttitleTitle as subject-
subjectgenreGenre or form as subject-
subjecttopicAny topical subjects not appropriate in the above subject fields-
freetextFree text-
idThe id returned in the id element of the atom entry. Use full id (id:http://www.nb.no/services/search/v2/search/54a1f2ba158844958c5326e09bb1e4a1) or just the last part (id:54a1f2ba158844958c5326e09bb1e4a1)-

Combining multiple terms

When several terms and phrases are combined, the default behaviour is that the search engine will return documents that have ALL the terms or phrases present. To alter this behaviour you may use the OR operator (OR or |) and the NOT operator (-).

To search for documents that must contain both oslo and christiania use the query:

oslo christiania

To search for documents containing either <oslo> or <christiania> use the query:

oslo OR christiania, alternative syntax: oslo | christiania

Note that the OR operator affects only the preceding and succeeding term, so to search for documents that may contain oslo but must contain christiania use the query:

havn oslo OR christiania

To search for documents that must contain oslo but not christiania use the query:

oslo -christiania

Grouping

Parantheses may be used to group query terms. To search for documents containing oslo and havn or drammen and havn use the query:

(oslo OR drammen) havn

Ranking and Sorting

The default sorting of a result list is based on a calculated rank value (relevance score) for each of the resulting documents from a set of relevancy parameters. A higher ranking value implies that the document with this ranking value is expected to be more relevant with respect to the actual query. The most relevant documents will be listed first in the result list.

The following single fields may be used for sorting the results:

Syntax: sort=<field>:<asc|desc>

Example: http://www.nb.no/services/search/v2/search?q=Henrik+Ibsen+Terje+Vigen&sort=title:asc

Query Profiles

To change the default behavior of the API one may specify a query profile.

Syntax: qp=<query profile name>

Currently the only query profile supported is the default profile.

Faceting and filtering

The client may ask for facets to be included In the request. Facets enables constraining the query based on values in the documents returned in the response. To return all facets available use: facet=all

Request example: http://www.nb.no/services/search/v2/search/?q=snikksnakke&facet=all&itemsPerPage=1

Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:ns2="http://a9.com/-/spec/opensearch/1.1/" xmlns:ns3="http://www.w3.org/1999/xhtml">
  <id>http://www.nb.no/atomfeed</id>
  <updated>2011-05-20T12:16:20.713+02:00</updated>
  <title type="text">NBSearch</title>
  <subtitle type="text">Nasjonalbibliotekets general Search API for client applications, results: 1 - 0 of 20</subtitle>
  <ns2:itemsPerPage>0</ns2:itemsPerPage>
  <ns2:startIndex>1</ns2:startIndex>
  <ns2:totalResults>20</ns2:totalResults>
  <ns2:Query startIndex="1" searchTerms="snikksnakke" role="request"/>
  <link href="http://www.nb.no/services/search/v2/search?q=snikksnakke&amp;itemsPerPage=0&amp;facet=all" rel="self"/>
  <link href="http://www.nb.no/services/search/v2/search?q=snikksnakke&amp;itemsPerPage=0&amp;facet=all&amp;startIndex=1" rel="next"/>
  <link href="http://www.nb.no/services/search/v2/search?alt=application/opensearchdescription+xml" type="application/opensearchdescription+xml" rel="search"/>
  <nb:facets xmlns:nb="http://www.nb.no/xml/search/1.0/">
    <nb:facet>
      <nb:name>year</nb:name>
      <nb:values>
        <nb:value nb:count="4">1999</nb:value>
        <nb:value nb:count="3">1997</nb:value>
        <nb:value nb:count="3">1998</nb:value>
        <nb:value nb:count="2">1985</nb:value>
        <nb:value nb:count="1">1953</nb:value>
        <nb:value nb:count="1">1957</nb:value>
        <nb:value nb:count="1">1979</nb:value>
        <nb:value nb:count="1">1984</nb:value>
        <nb:value nb:count="1">1993</nb:value>
        <nb:value nb:count="1">1994</nb:value>
        <nb:value nb:count="1">1996</nb:value>
        <nb:value nb:count="1">2000</nb:value>
      </nb:values>
    </nb:facet>
    <nb:facet>
      <nb:name>publisher</nb:name>
      <nb:values>
        <nb:value nb:count="5">Kunnskapsforl.</nb:value>
        <nb:value nb:count="2">Orion</nb:value>
        <nb:value nb:count="1">Crossword forl.</nb:value>
        <nb:value nb:count="1">Egmont bøker Fredhøi</nb:value>
        <nb:value nb:count="1">Grøndahl Dreyer</nb:value>
        <nb:value nb:count="1">Gyldendal</nb:value>
        <nb:value nb:count="1">Kunnskapsforlaget</nb:value>
        <nb:value nb:count="1">Sørlies bokhus</nb:value>
        <nb:value nb:count="1">Tanum</nb:value>
        <nb:value nb:count="1">Tanum-Norli</nb:value>
      </nb:values>
    </nb:facet>
    <nb:facet>
      <nb:name>subjecttopic</nb:name>
      <nb:values>
        <nb:value nb:count="1">Utale bøyning ordforkl geografiske navn</nb:value>
        <nb:value nb:count="1">kryssord leksikon</nb:value>
        <nb:value nb:count="1">kryssord ordbøker</nb:value>
        <nb:value nb:count="1">norsk språk nynorsk ordbøker norske ordböker</nb:value>
        <nb:value nb:count="1">norsk språk ordbøker rettskriving</nb:value>
        <nb:value nb:count="1">norsk språk ordbøker språk-ordbøker ordbøker-bokmål bokmål rettskrivning rettskriving</nb:value>
        <nb:value nb:count="1">ordbøker norsk språk</nb:value>
      </nb:values>
    </nb:facet>
    <nb:facet>
      <nb:name>namecreator</nb:name>
      <nb:values>
        <nb:value nb:count="8">Danielsen, Daniel</nb:value>
        <nb:value nb:count="2">Guttu, Tor</nb:value>
        <nb:value nb:count="2">Sandvei, Marius</nb:value>
        <nb:value nb:count="1">Ashley, Anne</nb:value>
        <nb:value nb:count="1">Fossestøl, Bernt</nb:value>
        <nb:value nb:count="1">Lander, Leena</nb:value>
        <nb:value nb:count="1">Schwach, Jarle</nb:value>
        <nb:value nb:count="1">Sverdrup, Jakob</nb:value>
        <nb:value nb:count="1">Sørlie, Einar</nb:value>
      </nb:values>
    </nb:facet>
    <nb:facet>
      <nb:name>day</nb:name>
      <nb:values>
        <nb:value nb:count="1">07</nb:value>
        <nb:value nb:count="1">11</nb:value>
        <nb:value nb:count="1">19</nb:value>
      </nb:values>
    </nb:facet>
    <nb:facet>
      <nb:name>month</nb:name>
      <nb:values>
        <nb:value nb:count="1">03</nb:value>
        <nb:value nb:count="1">04</nb:value>
        <nb:value nb:count="1">09</nb:value>
      </nb:values>
    </nb:facet>
    <nb:facet>
      <nb:name>languages</nb:name>
      <nb:values>
        <nb:value nb:count="12">nob</nb:value>
        <nb:value nb:count="3">Norsk</nb:value>
        <nb:value nb:count="1">mul</nb:value>
        <nb:value nb:count="1">nno</nb:value>
      </nb:values>
    </nb:facet>
    <nb:facet>
      <nb:name>mediatype</nb:name>
      <nb:values>
        <nb:value nb:count="17">Bøker</nb:value>
        <nb:value nb:count="3">Aviser</nb:value>
      </nb:values>
    </nb:facet>
    <nb:facet>
      <nb:name>digital</nb:name>
      <nb:values>
        <nb:value nb:count="20">True</nb:value>
      </nb:values>
    </nb:facet>
  </nb:facets>
</feed>

Fine-grained Facet control (CURRENTLY NOT SUPPORTED)

In order to control which facets to return as well as the maximum number and the ordering of the facet values use:

facet=<facetname>:<numberoffacetvalues>:<order>

Possible values for facetname :

Possible values for order :

The default value for order is count.

Examples:

Constraining a query

Filter

In addition to constraining queries using facets one may use a filter. A filter may contain any valid query. A possible use case for filtering may be when we want to constrain without the end user knows about it. To implement a search service providing search only in radio programs one would filter as follows: http://www.nb.no/services/search/v2/search/atom/?q=hamsun&filter=mediatype:radio

References