Skip to page content.

Menu
Search

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 search/browse access.

URLs and Supported Requests

The Authority Cluster Resource supports these operations:

Operation Resource URL HTTP METHOD Response
Get Data https://www.viaf.org/viaf/{VIAF_Identifier} GET Data
Get VIAF Data by LCCN ID
 https://www.viaf.org/viaf/lccn/{Library_of_Congress_Controll_Number} GET Data
Get VIAF Data by Source ID https://www.viaf.org/viaf/sourceID/{Authority_Source_Code}|{Local_Authority_ID} GET Data
SRU Search
 https://viaf.org/viaf/search?query={CQL_Query}&maximumRecords=10&startRecord=1&sortKeys=holdingscount GET Data
SRU Browse https://viaf.org/search?scanClause={CQL_Query}&responsePosition=10&maximumTerms=20 GET Data
Auto Suggest
 https://viaf.org/viaf/AutoSuggest?query={Search_Terms}&callback={Optional_Callback_Name} GET Data

Response Formats

The Authority Cluster endpoint allows a client to specify the response format through content negotiation.

Data Responses

Response Format HTTP Accept Header
HTML 

*/*

application/xhtml+xml

text/html
XML application/xml

SRU Search and Browse Responses

 

Response Format HTTP Accept header
HTML (default)

*/*

application/xhtml+xml

text/html
SRU 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
BIBSYS BIBSYS
BLBNB National Library of Brazil
BNC National Library of Catalonia
BNCHL National Library of Chile
BNE Biblioteca Nacional de España
BNF Bibliothèque Nationale de France
BNL National Library of Luxembourg
B2Q National Library and Archives of Quèbec
CYT National Central Library, Taiwan
DBC DBC (Danish Bibliographic Center)
DNB Deutsche Nationalbibliothek
EGAXA Bibliotheca Alexandrina (Egypt)
ERRR National Library of Estonia
ICCU Istituto Centrale per il Catalogo Unico
ISNI ISNI
JPG Getty Research Institute
KRNLK National Library of Korea
LC Library of Congress/NACO
LAC Library and Archives Canada
LNB National Library of Latvia
LNL Lebanese National Library
MRBNR National Library of Morocco
NDL National Diet Library, Japan
NII National Institute of Informatics (Japan)
NKC National Library of the Czech Republic
NLA National Library of Australia
NLB National Library Board, Singapore
NLI National Library of Israel
NLIara National Library of Israel (Arabic)
NLIcyr National Library of Israel (Cyrillic)
NLIheb National Library of Israel (Hebrew)
NLIlat National Library of Israel (Latin)
NLP National Library of Poland
NLR National Library of Russia
NSK National and University Library in Zagreb
NSZL National Szèchènyi Library, Hungary
NTA National Library of the Netherlands
NUKAT NUKAT Center of Warsaw University Library
N6I National Library of Ireland
PERSEUS PERSEUS
PTBNP Biblioteca Nacional de Portugal
RERO RERO.Library Network of Western Switzerland
SELIBR National Library of Sweden
SRP Syriac Reference Portal
SUDOC Sudoc [ABES], France
SWNL Swiss National Library
UIY National and University Library of Iceland (NULI)
VLACC Flemish Public Libraries
WKP Wikidata
W2Z National Library of Norway
XA
 xA (eXtended Authorities)
XR xR (eXtended Relationships)
FAST FAST

SRU Searching and Browsing

Search Parameters

Parameter Required? Description
 Expected/Sample Value
query Yes CQL query query=cql.any+%3D+%22Jane+Austen%22
recordSchema No The record schema to return information in. By default VIAF XML is returned

Record schema values:

  • http://viaf.org/VIAFCluster
  • http://viaf.org/BriefVIAFCluster
  • info:srw/schema/1/marcxml-v1.1
  • info:srw/schema/1/unimarc-v0.1
  • http://www.w3.org/1999/02/22-rdf-syntax-ns
  • info:srw/schema/1/JSON
maximumRecords No

The number of records to return per page.

The maximum records which can be returned depends on the recordSchema.

  • Only 10 VIAF Cluster records can be returned.
  • 250 of any other type records can be returned.

default Full VIAF Cluster records - 10

default all other types of records - 100
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
callback No JSONP Callback function name  

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
callback No JSONP Callback function name  

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 (search 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 within the authority record. 110, 410, 510
 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 - names which are the preferred form in an authority record. 1xx local.mainHeadingEl+exact+"Diana%2C+Princess+of"
local.names Names - any name preferred or alternate 1xx, 4xx, 5xx local.names+%3D+"Existentialism"
local.personalNames Personal Names within the authority record. 100, 400, 500 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.

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

Return a VIAF XML record for VIAF identifier 102333412:

curl --location 'https://viaf.org/viaf/102333412' \
--header 'Accept: application/xml' \

Return VIAF XML record based on Library of Congress Control Number 79032879:

curl --location 'https://viaf.org/viaf/lccn/n79032879' \
--header 'Accept: application/xml' \

Return VIAF XML record based on Germany National Library (Deutsche Nationalbibliothek) source ID 1034425390

curl --location 'https://viaf.org/viaf/sourceID/DNB|103442' \
--header 'Accept: application/xml' \

SRU Search Examples

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

curl --location 'https://viaf.org/viaf/search?query=cql.any+%3D+%22Jane+Austen%22' \
--header 'Accept: application/xml' \

SRU Browse Examples

Browse for term "OCLC":

curl --location 'https://viaf.org/viaf/search/viaf?scanClause=cql.any+%3D+%22oclc%22&responsePosition=10&maximumTerms=20' \
--header 'Accept: application/xml' \

Auto Suggest Example

Get AutoSuggested records for the term "austen":

curl --location 'https://viaf.org/viaf/AutoSuggest?query=austen' \
--header 'Accept: application/json' \

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.