CTAN
Comprehensive TeX Archive Network

Query­ing CTAN with XML – Search­ing

The search func­tion­al­ity can be used pro­gram­mat­i­cally. This can be achieved with a HTTP get re­quest like

http://www.ctan.org/search/xml?phrase=knuth

Pa­ram­e­ters

Pa­ram­e­ters are passed in as URl pa­ram­e­ters.

phrase
The pa­ram­e­ter phrase con­tains the search phrase, i.e. the words or search ex­pres­sions to query for.
offset
This is the off­set for pag­ing. The ac­com­pa­ny­ing pa­ram­e­ter max con­tains the page size. This pa­ram­e­ter con­tains the first hit to be re­turned. It is a num­ber greater or equal to 0. If a neg­a­tive num­ber is passed in then it is re­placed by 0. If the off­set is larger than the num­ber of ac­tual hits then the list of hits will be empty.
max
This pa­ram­e­ter de­ter­mines the num­ber of hits max­i­mally re­turned. It is a num­ber in the range 1 to 256. Larger val­ues will be re­duced to 256. Lower val­ues will be re­placed by the de­fault value. If this pa­ram­e­ter is omit­ted then the de­fault value 16 will be used.
ext
This pa­ram­e­ter de­ter­mines whether the sec­tions are re­quested ex­plic­itly. The value is ei­ther true or false. For any other value the be­hav­ior is un­de­fined.

If the value is false then all de­fault sec­tions are searched. Other­wise the sec­tions to be searched have to be spec­i­fied with ad­di­tional pa­ram­e­ters.

The de­fault for this pa­ram­e­ter is false.

PKG
This pa­ram­e­ter de­ter­mines whether the pack­age sec­tion should be in­cluded into the search. The pack­age sec­tion con­tains the text fields of a pack­age en­try in the Cat­a­logue.

The de­fault for this pa­ram­e­ter is false.

AUTHORS
This pa­ram­e­ter de­ter­mines whether the au­thor sec­tion should be in­cluded into the search. The au­thor sec­tion con­tains the names of the con­trib­u­tors in the Cat­a­logue.

The de­fault for this pa­ram­e­ter is false.

TOPICS
This pa­ram­e­ter de­ter­mines whether the top­ics sec­tion should be in­cluded into the search. The top­ics sec­tion con­tains the text fields of the top­ics in the Cat­a­logue.

The de­fault for this pa­ram­e­ter is false.

PORTAL
This pa­ram­e­ter de­ter­mines whether the por­tal sec­tion should be in­cluded into the search. The por­tal sec­tion con­tains the text of the por­tal pages.

The de­fault for this pa­ram­e­ter is false.

Re­turn value

The body of the re­sponse con­tains the XML as in the fol­low­ing ex­am­ple:

<search-result numberOfHits='82' offset='0' max='16' phrase='knuth'>
  <search-hit title='Donald E. Knuth' path='/author/knuth' text=''/>
  <search-hit title='Package knuth-local' path='/pkg/knuth-local' text='Knuth&apos;s local information'/>
  <search-hit title='Package vf-knuth' path='/pkg/vf-knuth' text='Knuth on virtual fonts'/>
  <search-hit title='Package knuth-lib' path='/pkg/knuth-lib' text='A small library of MetaFont sources'/>
  <search-hit title='Package knuth-base' path='/pkg/knuth-base' text='The current state of Knuth&apos;s contributions'/>
  <search-hit title='Package knuth-errata' path='/pkg/knuth-errata' text='Knuth&apos;s published errata'/>
  <search-hit title='Package gen' path='/pkg/gen' text='Genealogy symbols'/>
  <search-hit title='Package knuth-letter' path='/pkg/knuth-letter' text='Knuth&apos;s example letter macros'/>
  <search-hit title='Package knuth-dist' path='/pkg/knuth-dist' text='The current state of Knuth's contributions'/>
  <search-hit title='Package picmac' path='/pkg/picmac' text='A picture mode in Plain TeX'/>
  <search-hit title='Package mfware' path='/pkg/mfware' text='Supporting tools for use with Metafont'/>
  <search-hit title='index-k.html' path='/pkg/index-k.html' text=''/>
  <search-hit title='Package cm' path='/pkg/cm' text='Computer Modern fonts'/>
  <search-hit title='Package gray' path='/pkg/gray' text='Fonts for gray-scales'/>
  <search-hit title='Package punk' path='/pkg/punk' text='Donald Knuth&apos;s punk font'/>
  <search-hit title='Package ransom' path='/pkg/ransom' text='A "very bad typewriter" font'/>
</search-result>  

The re­sult has the outer tag search-result. This tag has sev­eral at­tributes:

numberOfHits
This at­tribute con­tains the to­tal num­ber of hits found.
offset
This at­tribute con­tains the off­set at which the hits start. It is a rep­e­ti­tion of the in­put ar­gu­ment offset which might have been adapted.
max
This at­tribute con­tains the max­i­mal num­ber of hits in this junk. It is a rep­e­ti­tion of the in­put ar­gu­ment max which might have been adapted.
phrase
This at­tribute con­tains the search phrase. It is a rep­e­ti­tion of the in­put ar­gu­ment phrase which might have been adapted.

The tag search-result can have sev­eral in­ner tags:

<search-hit>
This in­ner tag rep­re­sents a sin­gle hit. It has the fol­low­ing at­tributes:
title
This at­tribute con­tains the page ti­tle of the hit.
path
This at­tribute con­tains the ab­so­lute path on the CTAN Por­tal of the hit.
text
This at­tribute con­tains some ad­di­tional text to dis­play.

Ex­cep­tions

In case of an er­ror the sta­tus code isn't 200. The body of the re­sponse con­tains more or less mean­ing­less text.

Guest Book Sitemap Contact Contact Author