-
Notifications
You must be signed in to change notification settings - Fork 3
DrawShield 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.
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.
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.
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
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.
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).
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
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
An automated process randomly selects an image from the gallery of submissions to be the "Gallery Image of the Day". The API allows access to this image in various formats:
https://drawshield.net/api/giotd/{FORMAT}
Where {format} is one of:
- src - the URL of the image as text
- img - the absolute path to the image (of little use externally)
- href - the URL of the gallery page as text
- html - some HTML containing the image, the date and the gallery reference number
The API allows the searching of a (reasonably complete) catalog of available charges, ordinaries and other elements:
https://drawshield.net/api/catalog/{item}
By default, the search is for exact matches only. If the {item} string contains an asterisk (*) anywhere in it then the search will match any item that contains the string (up to 10 matches).
If there is no match the string "Sorry, nothing found in catalog" is returned.
If there is exactly one match, a string will be returned, the first line of which will be the URL to an image in the catalog. The second line, if present, will be a list of the features available for a charge.
If there is more than one match there will be a line of text for each match showing the location of each match within the catalog hierarchy.
The API can randomly choose the image of a coat of arms for the user to attempt to re-create as closely as possible using DrawShield. (NOTE: It isn't always possible to do this, additionally all of the images are external to DrawShield so their continued existence is at the whim of their providers - if the image doens't exist just try another one). The API call is as follows:
https://drawshield.net/api/challenge/{group}
Where {group} is one of the following:
- coadb - images used on the website coadb.com
- publicarms - images from the book of public arms
- wappenwiki - images from the wappenwiki site
- wikipedia - images from wikipedia (guaranteed to be drawable in DrawShield)
- all - random selection from any of the above
The returned value is a string containing the url of the target image.
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.