LP#1657282: fix redirect of one-hit metarecord searches
[Evergreen.git] / docs / development / data_supercat.txt
1 Using Supercat
2 ==============
3
4 Introduction
5 ------------
6
7 You can use SuperCat to get data about ISBNs, metarecords, bibliographic
8 records, and authority records.
9
10 Throughout this section, replace `<hostname>` with the domain or subdomain
11 of your Evergreen installation to try these examples on your own system.
12
13 ISBNs
14 -----
15
16 Given one ISBN, Evergreen can return a list of related records and ISBNs,
17 including alternate editions and translations.  To use the Supercat
18 oISBN tool, use http or https to access the following URL.
19
20 ----
21 http://<hostname>/opac/extras/oisbn/<ISBN_to_query>
22 ----
23
24 For example, the URL http://gapines.org/opac/extras/oisbn/0439136350 returns
25 the following list of catalog record IDs and ISBNs:
26
27 [source,xml]
28 ----------------------------------------------------------------------------
29 <?xml version='1.0' encoding='UTF-8' ?>
30 <idlist metarecord='436139'>
31   <isbn record='5652044'>9780606323475</isbn>
32   <isbn record='5767568'>9780780673809</isbn>
33   <isbn record='1350528'>9780807286029</isbn>
34   <isbn record='5708164'>9780780669642</isbn>
35   <isbn record='2372013'>043965548X</isbn>
36   <isbn record='5804511'>8498386969</isbn>
37   <isbn record='4132282'>9780786222742</isbn>
38   <isbn record='1530458'>9788478885190</isbn>
39   <isbn record='2003291'>0736650962</isbn>
40   <isbn record='1993002'>8478885196</isbn>
41   <isbn record='1187595'>9780439554923</isbn>
42   <isbn record='4591175'>8478885196</isbn>
43   <isbn record='5676282'>0807282324</isbn>
44   <isbn record='2363352'>8478885196</isbn>
45   <isbn record='2315122'>1480614998</isbn>
46   <isbn record='2304130'>8478886559</isbn>
47   <isbn record='2012565'>9780613371063</isbn>
48   <isbn record='5763645'>9782070528189</isbn>
49   <isbn record='2383286'>0786222743</isbn>
50   <isbn record='2489670'>9780329232696</isbn>
51   <isbn record='1681685'>9780807282311</isbn>
52   <isbn record='2160095'>0807286028</isbn>
53   <isbn record='2219885'>9789500421157</isbn>
54   <isbn record='1934218'>9780613359580</isbn>
55   <isbn record='5682871'>9781594130021</isbn>
56   <isbn record='1281164'>0807283150</isbn>
57   <isbn record='1666656'>0747542155</isbn>
58   <isbn record='4717734'>8478886559</isbn>
59 </idlist>
60 ----------------------------------------------------------------------------
61
62 Records
63 -------
64
65 Record formats
66 ~~~~~~~~~~~~~~
67
68 First, determine which format you'd like to receive data in.  To see the
69 available formats for bibliographic records, visit 
70 ----
71 http://<hostname>/opac/extras/supercat/formats/record
72 ----
73
74 Similarly, authority record formats can be found at
75 http://libcat.linnbenton.edu/opac/extras/supercat/formats/authority
76 and metarecord formats can be found at
77 http://libcat.linnbenton.edu/opac/extras/supercat/formats/metarecord
78
79 For example, http://gapines.org/opac/extras/supercat/formats/authority
80 shows that the Georgia Pines catalog can return authority records in the
81 formats _opac_, _marc21_, _marc21-full_, and _marc21-uris_.  Supercat
82 also includes the MIME type of each format, and sometimes also refers
83 to the documentation for a particular format.
84
85 [source,xml]
86 ----------------------------------------------------------------------------
87 <?xml version='1.0' encoding='UTF-8' ?>
88 <formats>
89   <format>
90     <name>opac</name>
91     <type>text/html</type>
92   </format>
93   <format>
94     <name>marc21</name>
95     <type>application/xml</type>
96     <docs>http://www.loc.gov/marc/</docs>
97   </format>
98   <format>
99     <name>marc21-full</name>
100     <type>application/xml</type>
101     <docs>http://www.loc.gov/marc/</docs>
102   </format>
103   <format>
104     <name>marc21-uris</name>
105     <type>application/xml</type>
106     <docs>http://www.loc.gov/marc/</docs>
107   </format>
108 </formats>
109 ----------------------------------------------------------------------------
110
111 [NOTE]
112 ============================================================================
113 atom-full is currently the only format that includes holdings and availability
114 data for a given bibliographic record.
115 ============================================================================
116
117
118 Retrieve records
119 ~~~~~~~~~~~~~~~~
120
121 You can retrieve records using URLs in the following format:
122 ----
123 http://<hostname>/opac/extras/supercat/retrieve/<format>/<record-type>/<record-ID>
124 ----
125
126 For example, http://gapines.org/opac/extras/supercat/retrieve/mods/record/33333
127 returns the following record.
128
129 [source,xml]
130 ----------------------------------------------------------------------------
131 <?xml version="1.0"?>
132 <modsCollection xmlns="http://www.loc.gov/mods/" xmlns:mods="http://www.loc.gov/mods/" version="3.0">
133   <mods xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:mods="http://www.loc.gov/mods/" xsi:schemaLocation="http://www.loc.gov/mods/ http://www.loc.gov/standards/mods/mods.xsd">
134     <titleInfo>
135       <title>Words and pictures /</title>
136     </titleInfo>
137     <name type="personal">
138       <namePart xmlns:xlink="http://www.w3.org/TR/xlink">Dodd, Siobhan</namePart>
139       <role>
140         <text>creator</text>
141       </role>
142     </name>
143     <typeOfResource xmlns:xlink="http://www.w3.org/TR/xlink">text</typeOfResource>
144     <originInfo xmlns:xlink="http://www.w3.org/TR/xlink">
145       <place>
146         <code authority="marc">mau</code>
147       </place>
148       <place>
149         <text>Cambridge, Mass</text>
150       </place>
151       <publisher>Candlewick Press</publisher>
152       <dateIssued>1992</dateIssued>
153       <edition>1st U.S. ed.</edition>
154       <issuance>monographic</issuance>
155     </originInfo>
156     <language authority="iso639-2b">eng</language>
157     <physicalDescription>
158       <form authority="marcform">print</form>
159       <extent>1 v. (unpaged) : col. ill. ; 26 cm.</extent>
160     </physicalDescription>
161     <abstract>Simple text with picture cues accompany illustrations depicting scenes of everyday life familiar to children, such as getting dressed, attending a party, playing in the park, and taking a bath.</abstract>
162     <targetAudience>juvenile</targetAudience>
163     <note type="statement of responsibility">Siobhan Dodds.</note>
164     <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcshac">
165       <topic>Family life</topic>
166       <topic>Fiction</topic>
167     </subject>
168     <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
169       <topic>Vocabulary</topic>
170       <topic>Juvenile fiction</topic>
171     </subject>
172     <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
173       <topic>Rebuses</topic>
174     </subject>
175     <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
176       <topic>Picture puzzles</topic>
177       <topic>Juvenile literature</topic>
178     </subject>
179     <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
180       <topic>Picture books for children</topic>
181     </subject>
182     <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
183       <topic>Picture dictionaries, English</topic>
184       <topic>Juvenile literature</topic>
185     </subject>
186     <subject xmlns:xlink="http://www.w3.org/TR/xlink" authority="lcsh">
187       <topic>Vocabulary</topic>
188       <topic>Juvenile literature</topic>
189     </subject>
190     <classification authority="lcc">PZ7.D66275 Wo 1992</classification>
191     <classification authority="lcc">PN6371.5 .D63 1992x</classification>
192     <classification authority="ddc" edition="20">793.73</classification>
193     <identifier type="isbn">1564020428 :</identifier>
194     <identifier type="isbn">9781564020420</identifier>
195     <identifier type="lccn">91071817</identifier>
196     <recordInfo xmlns:xlink="http://www.w3.org/TR/xlink">
197       <recordContentSource>DLC</recordContentSource>
198       <recordCreationDate encoding="marc">920206</recordCreationDate>
199       <recordChangeDate encoding="iso8601">20110608231047.0</recordChangeDate>
200       <recordIdentifier source="GaAaGPL">33333</recordIdentifier>
201     </recordInfo>
202   </mods>
203 </modsCollection>
204 ----------------------------------------------------------------------------
205
206 Recent records
207 ~~~~~~~~~~~~~~
208
209 SuperCat can return feeds of recently edited or created authority and bibliographic records:
210
211 ----
212 http://<hostname>/opac/extras/feed/freshmeat/<feed-type>/<record-type>/<import-or-edit>/<limit>/<date>
213 ----
214
215 Note the following features:
216
217 * The limit records imported or edited following the supplied date will be returned. If you do not supply a date, then the most recent limit records will be returned.
218 * If you do not supply a limit, then up to 10 records will be returned.
219 * feed-type can be one of atom, html, htmlholdings, marcxml, mods, mods3, or rss2.
220
221 Example: http://gapines.org/opac/extras/feed/freshmeat/atom/biblio/import/10/2008-01-01
222
223 Filtering by Org Unit
224 ^^^^^^^^^^^^^^^^^^^^^
225
226 You can generate a similar list, with the added ability to limit by Org Unit, using the item-age browse axis.
227
228 To produce an RSS feed by item date rather than bib date, and to restrict it to a particular system within a consortium:
229
230 Example: http://gapines.org/opac/extras/browse/atom/item-age/ARL-BOG/1/10
231
232 Note the following:
233
234 * ARL-BOG should be the short name of the org unit you're interested in
235 * 1 is the page (since you are browsing through pages of results)
236 * 10 is the number of results to return per page
237
238 Modifying the 'atom' portion of the URL to 'atom-full' will include catalog links in the results:
239
240 Example: http://gapines.org/opac/extras/browse/atom-full/item-age/ARL-BOG/1/10
241
242 Modifying the 'atom' portion of the URL to 'html-full' will produce an HTML page that is minimally formatted:
243
244 Example: http://gapines.org/opac/extras/browse/html-full/item-age/ARL-BOG/1/10
245
246