The DrawShield API

A Plea to API users

DrawShield is hosted on a very small AWS LightSail, with a fixed amount of resource, it does NOT scale under load. Please rate-limit your use of the remote API to no more than a handful of requests per second. Any more is likely to overload the server possibly causing it to fail.

Options for GET and POST

If the drawshield code is installed on a PHP enabled web-server (such as drawshield.net) it can be invoked either by a GET or a POST request. An example GET request would be:

http://drawshield.net/include/drawshield.php?blazon=azure%20a%20bend%20or

If you install the drawshield code on your own server then obviously the URL and the initial path may be different. Note that, although this method simple it is not the most flexible as it cannot be used to generate a blazon from a file and there is an upper limit to the length of the URL that varies from server to server.

The HTTP POST request is the recommended method as it gives the greatest flexibility and range of options (described below). This the method used by the drawshield.net website "create" page.

Except where noted below, the GET and POST methods to drawshield accept the same set of arguments. All argument names and values must be lowercase, except for the blazon, which may in mixed case and contain accented characters.

Unrecognised arguments are silently ignored (this includes miss-spellings of the accepted arguments, so check your request carefully).

blazon

This is the only mandatory argument, although it can be blank, in which case an empty shield is constructed and returned. The value must be entity encoded.

As noted above, mixed case and accented characters are supported (although this is not necessary, for parsing purposes the program will lowercase all input and "collapse" accented characters to their unaccented versions). Case and accents are preserved in strings, for example vert the word "Olé" argent will display as shown.

blazonfile

This argument is only available with the POST method. If a form includes multi-part data with the name "blazonfile", a filename that ends in ".txt" and is less than 100,000 characters long then the contents of that multi-part data will be used as the input blazon. Note that the existence of blazonfile will take precedence over a blazon given in the "blazon" argument.

outputformat

This argument determines the output format of the drawn shield, allowable values are:

• svg - SVG vector graphic format, XML data rendered as an image by your browser (default)
• jpg (or jpeg) - JPEG image
• webp - Google's WebP Image Format
• png - PNG image with a transparent background
• json - This format combines several types of data in a JSON wrapper, see The JSON Output Format

(Note that if the argument "asfile" is present then this argument is ignored - the argument "saveformat" is used instead)

size

This argument is slightly mis-named in that it is actually the width of the resulting image. It will be coerced to be at least 100 but has no upper limit. The default value is 500. It represents the width in pixels of the rendered image. The height of the image will usually be 1.2 times the width but some shapes have slightly different values.

shape

This option sets the outline shape of the shield, allowable values are those shown in the preferences pane on the Drawshield.net create page.

ar

This option only makes a difference if the flag shape is chosen - it sets the proportions (aspect ratio) of the flag and can be specified either as a ratio (e.g. 9:10) or a decimal value (e.g. 0.9). The value is automatically constrained to sensible limits.

palette

This option sets the choice of colours to be used in displaying the shield. (There is no defined meaning of heraldic colours other than, for example, "gules" is to be represented as something resembling "red"). Various authorities have developed their own colour choices and drawshield supports the option values shown on the preferences pane of the drawshield.net create page.

You can define your own colour palette, following the instructions here Defining Colour Palettes.

Additional Colour Names

The palette above refers to the colour values for the standard heraldic named colours. In addition to these it is also possible use sets of other colours, that are NOT heraldic but are useful in specific situations like flags, pauldrons and tartans. These additional colour sets can be enabled by the following options:

• webcols=yes - allow any of the named web colours to be used
• whcols=yes - allow any of the named Warhammer 40,000 colours from the Citadel Minatures paint range to be used
• tartancols=yes - allow any of the standard Tartan colour names to be used

For more details on these colours see the Colour Reference section in the visual catalog

effect

DrawShield supports some simple effects to give your shield the appearance of being constructed in a particular material. These effects are achieved by applying an SVG filter, most of which are based on those built in to Inkscape whose authors I would like to thank. All the filters except plain (which actually means "no filter") affect the colour values set by the palette. To get just the pure colours from your chosen palette select the "plain" value for effect. The available values are those shown in the preferences pane of the drawshield.net create page.

asfile

If this option is present then instead of returning the image the program will force the download of the image as a file

filename

This is the name that will be used for a downloaded file, if it is not given then 'shield' will be used. A suffix appropriate suitable for the file type will be added if not already present. Note that some browsers seem to ignore this and use their own naming conventions.

saveformat

This option selects the file format for the "asfile" option, it takes the same values as "outputformat" above, with the addition of:

• pdfltr - as a PDF file sized 8.5" x 11"
• pdfa4 - as a PDF file sized 210mm x 297mm

printable

This option forces SVG output at a width of 100% of the window (so all the format, saving and size options are ignored). The intention is to open this in a separate window which can then be printed using the browser printing dialog. It is probably of limited use in other contexts.

stage (Deprecated)

This was used to provide debugging information but there is now more complete data available in the json format. It has no effect.