# GF web services API examples

GF can be used interactively from the GF Shell. Some of the functionality availiable in the GF shell is also available via the GF web services API.

The GF Web Service API page describes the calls supported by the GF web service API. Below, we illustrate these calls by examples, and also show how to make these calls from JavaScript using the API defined in `pgf_online.js`.

Note that `pgf_online.js` was initially developed with one particular web application in mind (the minibar), so the server API was incomplete. It was simplified and generalized in August 2011 to support the full API.

These boxes show what the calls look like in the JavaScript API defined in `pgf_online.js`.
These boxes show the corresponding URLs sent to the PGF server.
  These boxes show the JSON (JavaScript data structures) returned by the PGF server. This will be passed to the callback function supplied in the call.

## Initialization

// Select which server and grammars to use:
var server_options = {
grammars_url: "http://www.grammaticalframework.org/grammars/",
grammar_list: ["Foods.pgf"] // It's ok to skip this
}
var server = pgf_online(server_options);

## Examples

// Get the list of available grammars
server.get_grammarlist(callback)
http://localhost:41296/grammars/grammars.cgi
  ["Foods.pgf","Phrasebook.pgf"]
// Select which grammar to use
server.switch_grammar("Foods.pgf")
// Get list of concrete languages and other grammar info
server.grammar_info(callback)
http://localhost:41296/grammars/Foods.pgf
  {"name":"Foods", "userLanguage":"FoodsEng", "startcat":"Comment", "categories":["Comment","Float","Int","Item","Kind","Quality","String"], "functions":["Boring","Cheese","Delicious","Expensive","Fish","Fresh", "Italian","Mod","Pizza","Pred","That","These","This","Those","Very", "Warm","Wine"], "languages":[{"name":"FoodsBul","languageCode":""}, {"name":"FoodsEng","languageCode":"en-US"}, {"name":"FoodsFin","languageCode":""}, {"name":"FoodsSwe","languageCode":"sv-SE"}, ...] }
// Get a random syntax tree
server.get_random({},callback)
http://localhost:41296/grammars/Foods.pgf?command=random
  [{"tree":"Pred (That Pizza) (Very Boring)"}]
// Linearize a syntax tree
server.linearize({tree:"Pred (That Pizza) (Very Boring)",to:"FoodsEng"},callback)
http://localhost:41296/grammars/Foods.pgf?command=linearize&tree=Pred+(That+Pizza)+(Very+Boring)&to=FoodsEng
  [{"to":"FoodsEng","text":"that pizza is very boring"}]
server.linearize({tree:"Pred (That Pizza) (Very Boring)"},callback)
http://localhost:41296/grammars/Foods.pgf?command=linearize&tree=Pred+(That+Pizza)+(Very+Boring)
  [{"to":"FoodsBul","text":"онази пица е много еднообразна"}, {"to":"FoodsEng","text":"that pizza is very boring"}, {"to":"FoodsFin","text":"tuo pizza on erittäin tylsä"}, {"to":"FoodsSwe","text":"den där pizzan är mycket tråkig"}, ... ]
// Parse a string
server.parse({from:"FoodsEng",input:"that pizza is very boring"},callback)
http://localhost:41296/grammars/Foods.pgf?command=parse&input=that+pizza+is+very+boring&from=FoodsEng
  [{"from":"FoodsEng", "brackets":{"cat":"Comment","fid":10,"index":0,"children":[{"cat":"Item","fid":7,"index":0,"children":[{"token":"that"},{"cat":"Kind","fid":6,"index":0,"children":[{"token":"pizza"}]}]},{"token":"is"},{"cat":"Quality","fid":9,"index":0,"children":[{"token":"very"},{"cat":"Quality","fid":8,"index":0,"children":[{"token":"boring"}]}]}]}, "trees":["Pred (That Pizza) (Very Boring)"]}]
// Translate to all available languages
server.translate({from:"FoodsEng",input:"that pizza is very boring"},callback)
  ...
// Translate to one language
server.translate({input:"that pizza is very boring", from:"FoodsEng", to:"FoodsSwe"}, callback)
http://localhost:41296/grammars/Foods.pgf?command=translate&input=that+pizza+is+very+boring&from=FoodsEng&to=FoodsSwe
  [{"from":"FoodsEng", "brackets":{"cat":"Comment","fid":10,"index":0,"children":[{"cat":"Item","fid":7,"index":0,"children":[{"token":"that"},{"cat":"Kind","fid":6,"index":0,"children":[{"token":"pizza"}]}]},{"token":"is"},{"cat":"Quality","fid":9,"index":0,"children":[{"token":"very"},{"cat":"Quality","fid":8,"index":0,"children":[{"token":"boring"}]}]}]}, "translations": [{"tree":"Pred (That Pizza) (Very Boring)", "linearizations": [{"to":"FoodsSwe", "text":"den där pizzan är mycket tråkig"}]}]}]
// Get completions (what words could come next)
server.complete({from:"FoodsEng",input:"that pizza is very "},callback)
http://localhost:41296/grammars/Foods.pgf?command=complete&input=that+pizza+is+very+&from=FoodsEng
  [{"from":"FoodsEng", "brackets":{"cat":"_","fid":0,"index":0,"children":[{"cat":"Item","fid":7,"index":0,"children":[{"token":"that"},{"cat":"Kind","fid":6,"index":0,"children":[{"token":"pizza"}]}]},{"token":"is"},{"token":"very"}]}, "completions":["boring","delicious","expensive","fresh","Italian","very","warm"], "text":""}]
// Get info about a category in the abstract syntax
server.browse({id:"Kind"},callback)
http://localhost:41296/grammars/Foods.pgf?command=browse&id=Kind&format=json
  {"def":"cat Kind", "producers":["Cheese","Fish","Mod","Pizza","Wine"], "consumers":["Mod","That","These","This","Those"]}
// Get info about a function in the abstract syntax
server.browse({id:"This"},callback)
http://localhost:41296/grammars/Foods.pgf?command=browse&id=This&format=json
  {"def":"fun This : Kind -> Item","producers":[],"consumers":[]}
// Get info about all categories and functions in the abstract syntax
server.browse({},callback)
http://localhost:41296/grammars/Foods.pgf?command=browse&format=json
  {"cats":{"Kind":{"def":"cat Kind", "producers":["Cheese","Fish","Mod","Pizza","Wine"], "consumers":["Mod","That","These","This","Those"]}, ...}, "funs":{"This":{"def":"fun This : Kind -> Item","producers":[],"consumers":[]}, ...} }
// Convert an abstract syntax tree to JSON
server.pgf_call("abstrjson",{tree:"Pred (That Pizza) (Very Boring)"},callback)
http://localhost:41296/grammars/Foods.pgf?command=abstrjson&tree=Pred+(That+Pizza)+(Very+Boring)
  {"fun":"Pred","fid":4, "children":[{"fun":"That","fid":1, "children":[{"fun":"Pizza","fid":0}]}, {"fun":"Very","fid":3, "children":[{"fun":"Boring","fid":2}]}]}
// Lookup the morphological analysis of a word
server.pgf_call("lookupmorpho",{input:"fish",from:"FoodsEng"},callback)
http://localhost:41296/grammars/Foods.pgf?command=lookupmorpho&input=fish&from=FoodsEng
  [{"lemma":"Fish","analysis":"s Pl"},{"lemma":"Fish","analysis":"s Sg"}]

Last modified: Thu Jun 16 17:08:04 CEST 2016