Reference API

You can access some of the reference material on this site through an Application Programming Interface (API) and so use the information in your own projects. An acknowledgement or link to the original source is always appreciated but is no mandatory. A contribution to the coffee and cake fund goes down even better(!) paypal.me/drawshield.

Overview

At the moment, all API calls use the HTTP verb "GET". The target URL is of the form:

https://drawshield.net/api/ACTION/ARGUMENT

The meaning of the ARGUMENT depends on the chosen ACTION, and there may also be additional options that can follow the ARGUMENT. Options always take the following form:

&OPTION=VALUE

Options must immediately follow the ARGUMENT, and more than one argument may be supplied.

By default, the returned data will be in JSON format. In the future I may make other formats available which would be selectable by setting an appropriate option.

Error Messages

If the API detects an error of any kind, either in the format of the request or during the execution of the request an error message will be returned. This will take the following JSON format:

    {
        "error": "ERROR MESSAGE"
    }

The following sections describe the various ACTIONs that are available.

Getting a Dictionary Definition of a Term

To search the available dictionaries for the definition of a heraldic term use the ACTION "define". The ARGUMENT is the term that you wish to search for (which must have special characters URL encoded). For example:

https://drawshield.net/api/define/azure

Return Value

If a definition is found it will be returned in JSON format as an array of two values, "content", which contains the term definition as a text string; and "URL" which is a link to the page containing the source of the definition. For example, the query above will return the following data: (I have added line breaks for readability, in reality the content string is a single line.)

    {
        "content": "Azure, bright blue, i.e. the colour of an eastern sky, probably derives the name from the Arabic lazura
        (conf. lapis lazuli, Gr. , Span. azul, Italian azurro, Fr. azur), the name being introduced from the East at the time 
        of the Crusades. It is sometimes called Inde from the sapphire, which is found in the East: (see example under cadency.) 
        Heralds who blazon by planets called it Jupiter, perhaps from his supposed rule over the skies; and when the names of 
        jewels are employed it is called Sapphire. Engravers represent it by an indefinite number of horizontal line.",
        "URL": "https://drawshield.net/reference/parker/a/azure.html"
    }

If the term cannot be found then the error message "Term not found" is returned.

Options

The following options and values are supported.

source: This allows you to choose the dictionary to search. Currently the available values are:

parker - to search Parker's Heraldic Dictionary only.
elvin - to search Elvins' Heraldic Dictionary only.
* - (the default) to search all available dictionaries.

Elvin's Dictionary has more entries (6,000) than Parkers (2,400) but the Parker definitions tend to be more detailed and descriptive. Other sources are likely to be added in future.

match: This allows you to require an exact match for the term, or to allow the API to conduct a "fuzzy" search. The available values are:

exact - the term must be found exactly as entered (except that all matches are case insensitive)
fuzzy - (strictly, any value that is not "exact") lets the program conduct a fuzzy match for the term. (See below).

Matching Strategy

Obviously, if an exact match is requested then only an exact (but case insensitive) match with a dictionary term is returned.

If a fuzzy match is requested, and a single dictionary is selected then we still search first for an exact match. If none is found we search all those terms that begin with the same letter and chose the term that most closely matches the requested term. The method used is to calculate a uniform cost Levenshtein distance to each entry and selecting the lowest value, provided that it is less than 7. In future, it may be possible to set this threshold through the option. If no entry with a Levenshtein distance below 7 is found then the error message "Term not found" is returned.

If you do NOT specify the dictionary, a slightly more complex approach is used, in which a series of searches are carried out and the first that succeeds is returned. The steps are as follows:

Search for an exact match in Parker
Search for an exact match in Elvin
Search for a fuzzy match in Parker
Search for a fuzzy match in Elvin
Return the "Term not found" error

Examples

Search Parker for an exact match for "azure":

https://drawshield.net/api/define/azure&source=parker&match=exact

Search everything for something like "abbased":

https://drawshield.net/api/define/abbased&match=fuzzy

(or, more simply):

https://drawshield.net/api/define/abbased

Future Developments

It is hoped to add further API calls in the future. Please get in touch if you have any suggestions for new calls, or for improvements and fixes to the existing calls.