Armoria API
API for Armoria — procedural heraldry generator and editor.
The API allows to GET random or predefined vector and raster heraldic images of a given size in a given format. It also allows to assign a specific coat of arms to a seed value (so called claiming).
API is hosted on Heroku. Please contact me directly if you want to use this API.
Try it: armoria.herokuapp.com/?size=500&format=svg&seed=123.
Remove seed to generate a random coat or arms: armoria.herokuapp.com/?size=500&format=svg
Basic usage
Parameters
Basic usage is to request coat of arms generation with URL parameters:
armoria.herokuapp.com/
format/size/seed
- format:
svg|png|jpg| default:svg
Armoria generates all images in svg by default. But as there are cases where svg cannot be used, the tool can convert images to png and jpg. Raster images quality depends on size, but relatively big images may be slow to get. There can be conversion issues, so svg is always preferable.
The main differences between png and jpg (also known as jpeg) are that png is lossless format and it supports transparency, while jpg is more compressed and has solid background. Out of these two, recommendation is to use use png.
- size:
number| default:500
Size in pixels. Can be any number set as 200 or 200px. For svg it just sets width and height, raster images are getting actually rescaled and size defines their quality.
- seed:
string| optional
Seed is a string (i.e. 123 is considered as "123") that defines procedural coat of arms generation. The same string will produce the same coat of arms irrespective of size and image format. This statement is only valid if generation code remains the same, so seed must not be used as a saving method.
If seed is not provided, the tool generates random 9-digits value. Omit seed parameter if you want to get random coat of arms for each request.
Seed is getting parsed to lower case, so Azgaar will produce the same image as azgaar. A few symbols are not supported and getting automatically replaced by underscore (#, ', ).
Query attributes
The same parameters (format, size, seed) can be used as query attributes. In this case parameters are not required:
armoria.herokuapp.com/?
format=svg&size=200&seed=123456789
Attributes that are supported only in query format are coa, shield and colors.
- coa:
string| supersedesseedt1: field tincture or pattern (fur)division: object withdivision,tandlineattributesordinaries: array withordinary,t,lineandsizeattributescharges: array withcharge,t,p,size,sinisterandreversedattributes
API can skip procedural generation and render specific coat of arms (coa). Attribute accepts json object encoded for URL usage.
To get coa string open Armoria GUI, edit coat of arms as you want and then click on Save → Copy COA string. It will copy coa string to your clipboard.
- shield:
string| default:random
Armoria supports >40 shield shapes. Any ot them can be used via API if exact names is passed as shield attribute. Available shapes:
heater | spanish | french | horsehead | horsehead2 | polish | hessen | swiss | boeotian | roman | kite | oldFrench | renaissance | baroque | targe | targe2 | pavise | wedged | round | oval | vesicaPiscis | square | diamond | no | flag | pennon | guidon | banner | dovetail | gonfalon | pennant | fantasy1 | fantasy2 | fantasy3 | fantasy4 | fantasy5 | noldor | gondor | easterling | erebor | ironHills | urukHai | moriaOrc
Custom colors
Armoria has 10 tinctures (colors) available by default:
| Tincture | Type | Represents | Chance | Color |
|----------|--------|--------------|--------|--------------------------------------------------------------------------------------------|
| argent | metal | silver | ~25% | #fafafa |
| or | metal | gold | ~16% |
#ffe066 |
| gules | colour | red | ~17% |
#d7374a |
| sable | colour | black | ~14% |
#333333 |
| azure | colour | blue | ~14% |
#377cd7 |
| vert | colour | green | ~7% |
#26c061 |
| purpure | colour | purple | ~13% |
#522d5b |
| murrey | stain | mulberry | ~1% |
#85185b |
| sanguine | stain | blood red | ~1% |
#b63a3a|
| tenné | stain | tawny | ~1% |
#cc7f19 |
It is possible to use custom tinctures or redefine default colors using query attributes.
Exact color can be set as a part of coa attribute. You can replace tincture name with color hex code, e.g. turn {"t1": "azure"} into hurting-eyes blue with {"t1": "#0000ff"}. URL must be encoded, so the link would be like armoria.herokuapp.com/?coa={%22t1%22:%22%230000ff%22}.
The resulting link is not readable, so you can also define colors using specific attributes for each of them like armoria.herokuapp.com/svg/500/1?gules=bb1100&or=FFD700&azure=00aaff. Hash symbol must be dropped.
Claiming
A specific coat of arms can be assigned to a value. In this case every time this seed (name) is requested, the same claimed coat of arms will be displayed. Assignment is stored in MongoDB Atlas with set (claim), update (reclaim) and delete (unclaim) operations allowed.
This functional can be used to set up a specific heraldic image for your name, country, city or any other word. Claims can be password-protected. For real objects like countries we are planning to set up coat of arms that resemble real ones. Admin users (Discord community members) have rights to update or delete claims it they found them inappropriate.
Claim
armoria.herokuapp.com/claim/
name/coa/key
- name:
string| non-numerical
Name is a string to be associated with a specific coat of arms, not the one auto-generated by the tool. Once assigned, name works as seed in its basic usage. Numerical names like 123 are assigned foe procedural generation and cannot be claimed. Name is getting parsed the same way as seed, so Armoria API will be parsed to armoria_api.
- coa:
string
Coat of arms object encoded for URL usage. Co copy it open Armoria GUI, edit coat of arms as you want and then click on Save → Copy COA string. See in details above.
- key:
string| optional
User-defined password. If omitted, no password will be set and anyone will be able to change or delete the claim. Password accepts any string. Please make sure you save it locally as there is no way to restore the key if you forget it.
Reclaim
armoria.herokuapp.com/claim/
name/coa/key
Raclaim updates the record in the database. If the current claim is password-protected, key value should be set. If not, it will accept any value or no value.
Unclaim
armoria.herokuapp.com/unclaim/
name/key
Unclaim removes the record from the database. For unclaim you need name and key (if was set on claim), but coa is not required.
Examples
Coat of arms generated for seed 123456789, rendered in svg, size is 400px:
Coat of arms generated for seed Armortown, rendered in jpg, size is 800px:
Random coat of arms in png, size 200px:
Coat of arms manually created in Armoria GUI, default format (svg) and size (500px):
Coat of arms manually created in Armoria GUI, rendered in png with size 200px:
Claim or reclaim name test (no password protection):
Claim or reclaim name test2 with password secret123:
Unclaim name test2 using password secret123:
License
The code is distributed under MIT.
Simple svg shapes and charges are self-made and available under CC0. Complex charges are historical, svg renders are coming from WappenWiki and available for non-commercial use under CC3. Source info is added to svg files. All images are manually optimized by me.