Querying CTAN with XML – Searching

The search functionality can be used programmatically. This can be achieved with a HTTP get request like

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

Parameters

Parameters are passed in as URl parameters.

phrase

The parameter phrase contains the search phrase, i.e. the words or search expressions to query for.

offset

This is the offset for paging. The accompanying parameter max contains the page size. This parameter contains the first hit to be returned. It is a number greater or equal to 0. If a negative number is passed in then it is replaced by 0. If the offset is larger than the number of actual hits then the list of hits will be empty.

max

This parameter determines the number of hits maximally returned. It is a number in the range 1 to 256. Larger values will be reduced to 256. Lower values will be replaced by the default value. If this parameter is omitted then the default value 16 will be used.

ext

This parameter determines whether the sections are requested explicitly. The value is either true or false. For any other value the behavior is undefined.

If the value is false then all default sections are searched. Otherwise the sections to be searched have to be specified with additional parameters.

The default for this parameter is false.

PKG

This parameter determines whether the package section should be included into the search. The package section contains the text fields of a package entry in the Catalogue.

The default for this parameter is false.

AUTHORS

This parameter determines whether the author section should be included into the search. The author section contains the names of the contributors in the Catalogue.

The default for this parameter is false.

TOPICS

This parameter determines whether the topics section should be included into the search. The topics section contains the text fields of the topics in the Catalogue.

The default for this parameter is false.

PORTAL

This parameter determines whether the portal section should be included into the search. The portal section contains the text of the portal pages.

The default for this parameter is false.

Return value

The body of the response contains the XML as in the following example:

<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 result has the outer tag search-result. This tag has several attributes:

numberOfHits

This attribute contains the total number of hits found.

offset

This attribute contains the offset at which the hits start. It is a repetition of the input argument offset which might have been adapted.

max

This attribute contains the maximal number of hits in this junk. It is a repetition of the input argument max which might have been adapted.

phrase

This attribute contains the search phrase. It is a repetition of the input argument phrase which might have been adapted.

The tag search-result can have several inner tags:

<search-hit>

This inner tag represents a single hit. It has the following attributes:

title

This attribute contains the page title of the hit.

path

This attribute contains the absolute path on the CTAN Portal of the hit.

text

This attribute contains some additional text to display.

Exceptions

In case of an error the status code isn't 200. The body of the response contains more or less meaningless text.