The JSON Output Format

The JSON Output Format

This format combines several items of useful data wrapped in a JSON object. It can be requested either as a file download or returned as an HTTP response, in either case the content is the same. In addition to specifying the 'outputformat' argument as 'json' you should also set the 'saveformat' argument to the type of image data that you would like the image to contain, if not given this will be 'png'.

Examples

To receive a JSON response containing a PNG image

POST/GET argument	Value
outputformat	json
saveformat	png

To receive a file download containing an SVG image

POST/GET argument	Value
outputformat	json
saveformat	svg
asfile	1
filename	myfile.json

JSON Objects

Top level object properties are as follows:

• image (string)

This is the shield image, in the requested format at the requested size. SVG format is provided as plain (but formatted) XML text data, the other formats are all encoded as base64 and will need to be decoded before use.

• tree (string)

This is the result of the parsing stage and contains a representation of the blazon in XML, conforming to the blazonML schema. This is the "pure" parse tree before any rendering has been attempted.

• mintree (string)

This is a simplified, pretty-printed version of the parse tree which is sometimes easier to read. For example the input "azure a mullet or" will produce the mintree value of:

  shield ID=N1-9
    simple ID=N1-3
      field ID=N1-2
        tincture ID=N1-0 index=1 origin=given
          colour ID=N1-1 keyterm=azure tokens=azure linenumber=1/
        /tincture
      /field
      objects ID=N1-4
        charge ID=N1-6 number=1 tokens=a mullet linenumber=1 keyterm=mullet/mullet
          tincture ID=N1-7 index=1 origin=given
            colour ID=N1-8 keyterm=or tokens=or linenumber=1/
          /tincture
          modifier type=chargemod keyterm=chg_data ID=S1-2 value=chg1/
        /charge
      /objects
    /simple
  /shield

Note that is extracted after any cross-references have been resolved and so may contain additional rendering hints. For example the "chg_data" modifier is the key to a cached version of the information needed to draw mullets (for use when drawing multiple charges). I'm not sure how useful this actually is, _so this behaviour is subject to change_, it may in future be a simple extract from the simple parse tree above.

• options (object)

This is the set of global options that were used to create the shield. These will either have been set elsewhere in the API call or take the default value. They are as described above, although note that some of the names change (hopefully in obvious ways), for example the API argument 'ar' becomes 'aspectRatio' in the set of options.

• messages (array of objects)

Each message object may contain the following properties:

• ID - (string - optional) if the message can be related to a specific part of the phrase tree this property gives value of the ID attribute of the relevant node
• category - (string) type of message, one of blazon / warning / internal / licence, all hopefully self-explanatory
• content - (string) the message text
• context - (string - optional) if this is an error message related to the blazon this is that part of the input blazon text in which the error occcured