Authority Cluster Resource

The VIAF Authority Cluster endpoint provides identification of name authority entities, access to their data representations and convenience functions for translation lookups from origin IDs as well as seach/browse access.

URLs and Supported Requests

The Authority Cluster Resource supports these operations:

Operation Resource URL HTTP METHOD Response
Identify http://www.viaf.org/viaf/{VIAF_Identifier} GET Redirect (303)
Get Data http://www.viaf.org/viaf/{VIAF_Identifier}/ GET Data
Get Data in Format http://www.viaf.org/viaf/{VIAF_Identifier}/{Record_Format} GET Data
Translate LCCN ID to VIAF URI
http://www.viaf.org/viaf/lccn/{Library_of_Congress_Controll_Number} GET Redirect (301)
Translate Source ID to VIAF URI http://www.viaf.org/viaf/sourceID/{Authority_Source_Code}|{Local_Authority_ID} GET Redirect (301)
SRU Search
http://viaf.org/viaf/search?query={CQL_Query}&maximumRecords=10&startRecord=1&sortKeys=holdingscount&httpAccept=text/xml GET Data
SRU Browse http://viaf.org/search?scanClause={CQL_Query}&responsePosition=10&maximumTerms=20 GET Data
Auto Suggest
http://viaf.org/viaf/AutoSuggest?query={Search_Terms}&callback={Optional_Callback_Name} GET Data

Response Formats

The VIAF Authority Cluster returns a mixture of of data responses and HTTP redirect responses.

Redirect Responses

Identify
Returns an HTTP 303 redirect response. This is the URI that stands for the real-world thing its corresponding data responses will describe. See the Example URLs section below for further explanation.
Translate Library of Congress Control Number to VIAF URI
Returns an HTTP 301 redirect response. This is is used so that clients who know the LCCN identifier to resolve the corresponding VIAF URI.
Translate Source ID to VIAF URI
Returns an HTTP 301 redirect response. This is is used so that clients who know the identifier used by contributing authority file to resolve the corresponding VIAF URI.

Data Responses

The Authority Cluster endpoint allows a client to specify the response format either through content negotiation or by using a URL suffix.

Response Format Content Negotiation mime type
Use with HTTP accept header
Examples Specifying the Response Format By URL
HTML

*/*

application/xhtml+xml

text/html

http://viaf.org/viaf/102333412/

Note the trailing slash that distinguishes the data response from the identfication URI.

VIAF XML application/xml http://viaf.org/viaf/102333412/viaf.xml
JSON application/json+links http://viaf.org/viaf/102333412/justlinks.json
RDF XML application/rdf+xml http://viaf.org/viaf/102333412/rdf.xml
JSON LD application/json+ld http://viaf.org/viaf/102333412/viaf.jsonld
RSS XML application/rss+xml http://viaf.org/viaf/102333412/rss.xml
MARC21 XML

application/marc21+xml

http://viaf.org/viaf/102333412/marc21.xml

MARC21 HTML

application/marc21+html

http://viaf.org/viaf/102333412/marc21.html

UNIMARC XML

application/unimarc+xml

http://viaf.org/viaf/102333412/unimarc.xml

UNIMARC HTML

application/unimarc+html

http://viaf.org/viaf/102333412/unimarc.html

SRU Search and Browse Responses

Response Format Content Negotiation mime type
Use with HTTP accept header
httpAccept Parameter Value(s)
HTML (default)

*/*

application/xhtml+xml

text/html

*/*

application/xhtml+xml

text/html

RSS application/rss+xml application/rss+xml
SRU XML

text/xml

application/xml

text/xml

application/xml

Translating Source Control Numbers to VIAF URIs

Local control numbers from the authority data sets can be translated to the corresponding VIAF URIs using an authority source code and the local identifier.

Authority Source Codes

Source Code Authority
ALL All source data within VIAF
BAV Biblioteca Apostolica Vaticana
BNE Biblioteca Nacional de España
BNF Bibliothèque Nationale de France
DNB Deutsche Nationalbibliothek
EGAXA Bibliotheca Alexandrina (Egypt)
ICCU Istituto Centrale per il Catalogo Unico
JPG Getty Research Institute
LC Library of Congress/NACO
LAC Library and Archives Canada
NKC National Library of the Czech Republic
NLA National Library of Australia
NLIara National Library of Israel (Arabic)
NLIcyr National Library of Israel (Cyrillic)
NLIheb National Library of Israel (Hebrew)
NLIlat National Library of Israel (Latin)
NUKAT The National Union Catalog of Poland
PTBNP Biblioteca Nacional de Portugal
SELIBR National Library of Sweden
SWNL Swiss National Library

SRU Searching and Browsing

Search Parameters

Parameter Required? Description
Expected/Sample Value
query Yes CQL query query=cql.any+%3D+%22Jane+Austen%22
httpAccept No The accept type to return the results as. By default html is returned

Response format values:

  • text/xml
  • application/xml
  • application/rss+xml
  • application/xhtml+xml
  • text/html
recordSchema No The record schema to return information in. By default VIAF XML is returned

Record schema values:

  • http://viaf.org/VIAFCluster
  • info:srw/schema/1/marcxml-v1.1
  • http://www.w3.org/1999/02/22-rdf-syntax-ns
maximumRecords No The number of records to return per page maximumRecords=10 
startRecord No The record to start with startRecord=1 
sortKey No

Modifies the search response to be ordered by WorldCat holdings count.

Presently, the only explicit sort option is holdings count. If the sortKey parameter is omitted, the default order will be the reverse order of loading.

Sort key values:

  • holdingscount

sortKey=holdingscount

Browse Parameters

Parameter Required? Description
Expected/Sample Value
scanClause Yes CQL query query=cql.any+%3D+%22Jane+Austen%22
maximumTerms No The number of items per page to include in the response. Similar to the maximum records parameter in the search response.
maximumTerms=20
responsePosition No

The value for this parameter will put the seed term (or closest match) at the specified position.

For example, if the API request includes the following parameters:

spanClaus=local.personalName+%3D+"wittgenstein"&maximumTerms=20&responsePosition=10

the closest match to the personal name "wittgenstein" will be at position 10 response and there will be 10 terms preceeding it and 9 after it in the list of 20.

responsePosition=10

The Contextual Query Language (CQL) Indices

A list of possible indices to be used in Search and SRU Search requests. You can browse values for each search term by going to http://viaf.org/viaf/search/viaf, selecting the index term on the right side of the page, entering a term, and pressing the "Browse" button.

Note that search terms can be:

  • = (one or more terms)
  • exact (searchs the exact string, including any punctuation)
  • any (for any of a list of terms)
  • all (for all the listed terms)
  • <
  • >
  • <=
  • >=
  • not
Index Description Expected/Sample Value(s)
cql.any All Fields cql.any+%3D+%22oclc%22
cql.serverChoice The server chooses which index to search using this value. cql.serverChoice+%3D+%22OCLC%22
local.corporateNames Corporate Names
local.corporateNames+%3D+%22OCLC%22
local.geographicNames Geographic Names (only jurisdictional names so far) local.geographicNames+%3D+%22Dublin%22
local.LCCN Library of Congress Number (about) local.LCCN+exact+%22n2001-50284%22
local.mainHeadingEl Preferred Name local.mainHeadingEl+exact+"Diana%2C+Princess+of"
local.names Names local.names+%3D+"Existentialism"
local.personalNames Personal Names local.names+all+"Kierkegaard"
local.source Source Record local.source+%3D+"telephone"
local.sources Source Authority File

Source codes:

  • viaf = All VIAF
  • nla = Australia
  • vlacc = Belgium (Flemish)
  • lac = Canada
  • nkc = Czech
  • egaxa = Egypt
  • bnf = France (BnF)
  • sudoc = France (Sudoc)
  • dnb = Germany
  • jpg = Getty (ULAN)
  • nszl = Hungary
  • nliara nlilat nlicyr nliheb = Israel
  • iccu = Italy
  • lc = Library of Congress (NACO)
  • bibsys = Norway (BIBSYS)
  • nukat = Poland
  • ptbnp = Portugal
  • bne = Spain
  • selibr = Sweden
  • swnl = Swiss (National Library)
  • rero = Swiss (RERO)
  • rsl = Russia
  • bav = Vatican
  • xa = xA

local.names+%3D+"george"+and+local.sources+%3D+"nla"

local.title Title local.title+%3D+"impressionism"
local.uniformTitleExpressions Uniform Titles (Expressions) local.uniformTitleExpressions+all+"Magic Flute"
local.uniformTitleWorks Uniform Titles (Works) local.uniformTitleWorks+all+"Magic Flute"

AutoSuggest

Authority Cluster autosuggest functionality provides a fast lookup and clients may pass a callback function name to wrap the response in a JSONP-style method call.

Request Forms

Parameters

Parameter Required? Description
query Yes The text to be queried against AutoSuggest. Use quotation marks if it contains spaces
callback No The JSONP callback function name to wrap the response data.

Example URLs

Redirect examples

Redirect responses do not return data directly. The following examples display the HTTP header response information.

Request to identify Jane Austin

GET http://viaf.org/viaf/102333412
Response
HTTP/1.1 303 See Other
Server: Apache-Coyote/1.1
Location: 88615663/
Content-Type: text/plain
Content-Length: 20
Date: Mon, 07 Jul 2014 18:36:58 GMT
See Other: 102333412/

The Identify response follows the Linked Data pattern that separates the URI that identifies a real world entity from the URI for the corresponding data description about that entity. The Identify response indicates that a client should redirect or make a subsequent request to the data response it returns.

Translate Library of Congress Control Number 79032879 to VIAF URI

GET http://viaf.org/viaf/lccn/n79032879
Response
HTTP/1.1 301 Moved Permanently
Server: Apache-Coyote/1.1
Location: http://viaf.org/viaf/102333412
Content-Type: application/redirect+xml
Content-Length: 0
Date: Fri, 11 Jul 2014 15:48:00 GMT

Translate Germany National Library (Deutsche Nationalbibliothek) source ID 1034425390 to VIAF URI

GET http://viaf.org/viaf/sourceID/DNB|1034425390
Response
HTTP/1.1 301 Moved Permanently
Server: Apache-Coyote/1.1
Location: http://viaf.org/viaf/102333412
Content-Type: application/redirect+xml
Content-Length: 0
Date: Fri, 11 Jul 2014 16:35:39 GMT

Data Examples

Return a VIAF XML record for VIAF identifier 102333412:

GET http://viaf.org/viaf/102333412/viaf.xml

Return an RDFXML record for the VIAF identifier 102333412:

GET http://viaf.org/viaf/102333412/rdf.xml

Returns a marc21 xml record for VIAF identifier 102333412:

GET http://viaf.org/viaf/102333412/marc21.xml

Return a JSON VIAF record for VIAF identifier 102333412:

GET http://viaf.org/viaf/102333412/justlinks.json

SRU Search Examples

Search for records where the authority includes the terms "Jane+Austen" and return RSS:

GET http://viaf.org/viaf/search?query=cql.any+%3D+%22Jane+Austen%22&httpAccept=application/rss%2bxml

Search for records where the authority includes the terms "Jane+Austen" and return records as SRU/XML:

GET http://viaf.org/viaf/search?query=cql.any+%3D+%22Jane+Austen%22&httpAccept=application/xml

Search for corporate term "OCLC":

GET http://viaf.org/viaf/search?query=local.corporateNames+all+%22OCLC%22

Search for name "George" in Australia (nla) only:

GET http://viaf.org/viaf/search/viaf?query=local.names+%3D+%22george%22+and+local.sources+%3D+%22nla%22
&recordSchema=http%3A%2F%2Fviaf.org%2FVIAFCluster&maximumRecords=100&startRecord=1

SRU Browse Examples

Browse for term "OCLC":

GET http://viaf.org/viaf/search/viaf?scanClause=cql.any+%3D+%22oclc%22&responsePosition=10&maximumTerms=20

Browse for term "OCLC" with the server identifying the index to use:

GET http://viaf.org/viaf/search/viaf?scanClause=cql.serverChoice+%3D+%22OCLC%22&responsePosition=10
&maximumTerms=20

Browse for corporate term "OCLC":

GET http://viaf.org/viaf/search/viaf?scanClause=local.corporateNames+%3D+%22OCLC%22&responsePosition=10
&maximumTerms=20

Browse for geographic name "Dublin":

GET http://viaf.org/viaf/search/viaf?scanClause=cql.any+%3D+%22Dublin%22&responsePosition=10&maximumTerms=20

Browse for LCCN "n2001-50284":

GET http://viaf.org/viaf/search/viaf?scanClause=local.LCCN+exact+%22n2001-50284%22&responsePosition=10
&maximumTerms=20

Browse for "Diana, Princess of":

GET http://viaf.org/viaf/search/viaf?scanClause=local.mainHeadingEl+exact+%22Diana%2C+Princess+of%22
&responsePosition=10&maximumTerms=20

Browse for "Existentialism":

GET http://viaf.org/viaf/search/viaf?scanClause=local.names+%3D+%22Existentialism%22&responsePosition=10
&maximumTerms=20

Browse for "Kierkegaard":

GET http://viaf.org/viaf/search/viaf?scanClause=local.names+all+%22Kierkegaard%22&responsePosition=10
&maximumTerms=20

Browse for "telephone":

GET http://viaf.org/viaf/search/viaf?scanClause=local.source+%3D+%22telephone%22&responsePosition=10
&maximumTerms=20

Browse for titles containing "impressionism":

GET http://viaf.org/viaf/search/viaf?scanClause=local.title+%3D+%22impressionism%22&responsePosition=10
&maximumTerms=20

Auto Suggest Example

Get AutoSuggested records for the term "austen":

http://viaf.org/viaf/AutoSuggest?query=austen

Notes

Merging of Clusters

Authority clusters can be merged together over time as additional data is received and algorithms are updated. When an authority cluster is merged into another the client will receive an HTTP 301 redirect to the new cluster URI.

VIAF Self Documenting Features

The Virtual International Authority File links national authority files, such as the German National Library and Library of Congress, to a single virtual authority file. See VIAF at a Glance for an overview. The VIAF service is self documenting:

Documentation Endpoint Description
viaf.org Overview; list of participating institutions.
viaf.org/viaf/data Data source description.
viaf.org/viaf/search/viaf Search/Retrieve via URL (SRU) search parameters for cluster records.

We are a worldwide library cooperative, owned, governed and sustained by members since 1967. Our public purpose is a statement of commitment to each other—that we will work together to improve access to the information held in libraries around the globe, and find ways to reduce costs for libraries through collaboration. Learn more »