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	http://viaf.org/viaf/102333412/viaf.json
JSON LD	application/ld+json	http://viaf.org/viaf/102333412/viaf.jsonld
RDF XML	application/rdf+xml	http://viaf.org/viaf/102333412/rdf.xml
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

Data responses can take a callback parameter to allow clients to retrieve JSON-P output.

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 application/json

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

SRU XML

text/xml

application/xml

text/xml

application/xml

application/json

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
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 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.

Request Forms

JSON: http://viaf.org/viaf/AutoSuggest?query=austen
JSONP: http://viaf.org/viaf/AutoSuggest?query=austen&callback=callbackFunctionName

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

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.

Authority Cluster Resource

URLs and Supported Requests

Response Formats

Redirect Responses

Data Responses

SRU Search and Browse Responses

Translating Source Control Numbers to VIAF URIs

Authority Source Codes

SRU Searching and Browsing

Search Parameters

Browse Parameters

The Contextual Query Language (CQL) Indices

AutoSuggest

Request Forms

Parameters

Example URLs

Redirect examples

Request to identify Jane Austin

Response

Translate Library of Congress Control Number 79032879 to VIAF URI

Response

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

Response

Data Examples

SRU Search Examples

SRU Browse Examples

Auto Suggest Example

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

Information for

Visit related sites

Subscribe to Tech Topics

Authority Cluster Resource

URLs and Supported Requests

Response Formats

Redirect Responses

Data Responses

SRU Search and Browse Responses

Translating Source Control Numbers to VIAF URIs

Authority Source Codes

SRU Searching and Browsing

Search Parameters

Browse Parameters

The Contextual Query Language (CQL) Indices

AutoSuggest

Request Forms

Parameters

Example URLs

Redirect examples

Request to identify Jane Austin

Response

Translate Library of Congress Control Number 79032879 to VIAF URI

Response

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

Response

Data Examples

SRU Search Examples

SRU Browse Examples

Auto Suggest Example

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

Follow OCLC Developer Network