Querying CTAN with JSON – Searching

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

http://www.ctan.org/search/json?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 JSON as in the following example:

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

The result is a JSON object. This object 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.

hits

This attribute contains the list of hits in this junk. Each hit is represented as JSON object with 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.