CTAN
Comprehensive TeX Archive Network

Query­ing CTAN with JSON – 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/json?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 JSON as in the fol­low­ing ex­am­ple:

{"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 re­sult is a JSON ob­ject. This ob­ject 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.
hits
This at­tribute con­tains the list of hits in this junk. Each hit is rep­re­sented as JSON ob­ject with 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