{"id":17296742,"url":"https://github.com/azgaar/armoria-api","last_synced_at":"2025-07-29T06:33:18.956Z","repository":{"id":39833040,"uuid":"336523729","full_name":"Azgaar/armoria-api","owner":"Azgaar","description":"Heraldry generator API","archived":false,"fork":false,"pushed_at":"2023-09-21T13:19:14.000Z","size":2089,"stargazers_count":38,"open_issues_count":2,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-14T11:44:55.721Z","etag":null,"topics":["api","express","generator","heraldry","nodejs","procedural-generation"],"latest_commit_sha":null,"homepage":"https://armoria.herokuapp.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Azgaar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-06T11:39:55.000Z","updated_at":"2025-03-04T17:49:44.000Z","dependencies_parsed_at":"2024-11-08T04:02:56.204Z","dependency_job_id":"43fc0e6a-4373-4d37-b8d9-89f9640358df","html_url":"https://github.com/Azgaar/armoria-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Azgaar/armoria-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azgaar%2Farmoria-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azgaar%2Farmoria-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azgaar%2Farmoria-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azgaar%2Farmoria-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Azgaar","download_url":"https://codeload.github.com/Azgaar/armoria-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Azgaar%2Farmoria-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267639569,"owners_count":24119780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","express","generator","heraldry","nodejs","procedural-generation"],"created_at":"2024-10-15T11:13:42.782Z","updated_at":"2025-07-29T06:33:18.930Z","avatar_url":"https://github.com/Azgaar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Armoria API\n\n_API for **[Armoria](https://github.com/Azgaar/Armoria)** — procedural heraldry generator and editor._\n\nThe 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_).\n\nAPI is hosted on _Heroku_. Please [contact me directly](mailto:maxganiev@yandex.com) if you want to use this API.\n\n![example1](https://armoria.herokuapp.com/png/120.0001)\n![example2](https://armoria.herokuapp.com/png/120.0002)\n![example3](https://armoria.herokuapp.com/png/120.0003)\n![example4](https://armoria.herokuapp.com/png/120.0004)\n![example5](https://armoria.herokuapp.com/png/120.0005)\n\nTry it: [armoria.herokuapp.com/?size=500\u0026format=svg\u0026seed=123](https://armoria.herokuapp.com/?size=500\u0026format=svg\u0026seed=123).\n\nRemove seed to generate a random coat or arms: [armoria.herokuapp.com/?size=500\u0026format=svg](https://armoria.herokuapp.com/?size=500\u0026format=svg)\n\n## Basic usage\n\n#### Parameters\n\nBasic usage is to request coat of arms generation with URL parameters:\n\n\u003e armoria.herokuapp.com/`format`/`size`/`seed`\n\n- **format:** `svg` | `png` | \u003csmall\u003edefault:\u003c/small\u003e `svg`\n\nArmoria generates all images in `svg` by default. But as there are cases where `svg` cannot be used, the tool can convert images to `png`. 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.\n\n- **size:** `number` | \u003csmall\u003edefault:\u003c/small\u003e `500`\n\nSize 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.\n\n- **seed:** `string` | \u003csmall\u003eoptional\u003c/small\u003e\n\nSeed 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.\n\nIf `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.\n\n`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 (`#`, `'`, ` `).\n\n#### Query attributes\n\nThe same parameters (`format`, `size`, `seed`) can be used as query attributes. In this case parameters are not required:\n\n\u003e armoria.herokuapp.com/?`format=svg`\u0026`size=200`\u0026`seed=123456789`\n\nAttributes that are supported only in query format are `coa`, `shield` and colors.\n\n- **coa:** `string` | \u003csmall\u003esupersedes `seed`\u003c/small\u003e\n  - `t1`: field tincture or pattern (fur)\n  - `division`: object with `division`, `t` and `line` attributes\n  - `ordinaries`: array with `ordinary`, `t`, `line` and `size` attributes\n  - `charges`: array with `charge`, `t`, `p`, `size`, `sinister` and `reversed` attributes\n\nAPI can skip procedural generation and render specific coat of arms (`coa`). Attribute accepts json object [encoded](https://meyerweb.com/eric/tools/dencoder/) for URL usage.\n\nTo get coa string open [Armoria GUI](https://github.com/Azgaar/Armoria), edit coat of arms as you want and then click on `Save` → `Copy COA string`. It will copy coa string to your clipboard.\n\n- **shield:** `string` | \u003csmall\u003edefault:\u003c/small\u003e `random`\n\nArmoria supports \u003e40 shield shapes. Any ot them can be used via API if exact names is passed as `shield` attribute. Available shapes:\n\n`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`\n\n### Custom colors\n\nArmoria has 10 [tinctures](\u003chttps://en.wikipedia.org/wiki/Tincture_(heraldry)\u003e) (colors) available by default:\n\n| Tincture | Type   | Represents | Chance | Color                                                                                        |\n| -------- | ------ | ---------- | ------ | -------------------------------------------------------------------------------------------- |\n| argent   | metal  | silver     | ~25%   | ![argent](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"argent\"}) #fafafa     |\n| or       | metal  | gold       | ~16%   | ![or](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"or\"}) #ffe066             |\n| gules    | colour | red        | ~17%   | ![gules](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"gules\"}) #d7374a       |\n| sable    | colour | black      | ~14%   | ![sable](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"sable\"}) #333333       |\n| azure    | colour | blue       | ~14%   | ![azure](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"azure\"}) #377cd7       |\n| vert     | colour | green      | ~7%    | ![vert](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"vert\"}) #26c061         |\n| purpure  | colour | purple     | ~13%   | ![purpure](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"purpure\"}) #522d5b   |\n| murrey   | stain  | mulberry   | ~1%    | ![murrey](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"murrey\"}) #85185b     |\n| sanguine | stain  | blood red  | ~1%    | ![sanguine](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"sanguine\"}) #b63a3a |\n| tenné    | stain  | tawny      | ~1%    | ![tenné](https://armoria.herokuapp.com/?format=png\u0026size=16\u0026coa={\"t1\":\"tenné\"}) #cc7f19       |\n\nIt is possible to use custom tinctures or redefine default colors using query attributes.\n\nExact 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}](https://armoria.herokuapp.com/?coa={%22t1%22:%22%230000ff%22}).\n\nThe 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\u0026or=FFD700\u0026azure=00aaff](https://armoria.herokuapp.com/svg/500/1?gules=bb1100\u0026or=FFD700\u0026azure=00aaff). Hash symbol must be dropped.\n\n## Claiming\n\nA 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.\n\nThis 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](https://discordapp.com/invite/X7E84HU) members) have rights to update or delete claims it they found them inappropriate.\n\n### Claim\n\n\u003e armoria.herokuapp.com/claim/`name`/`coa`/`key`\n\n- **name:** `string` | \u003csmall\u003enon-numerical\u003c/small\u003e\n\nName 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`.\n\n- **coa:** `string`\n\nCoat of arms object [encoded](https://meyerweb.com/eric/tools/dencoder/) for URL usage. Co copy it open [Armoria GUI](https://github.com/Azgaar/Armoria), edit coat of arms as you want and then click on `Save` → `Copy COA string`. See in details [above](#query-attributes).\n\n- **key:** `string` | \u003csmall\u003eoptional\u003c/small\u003e\n\nUser-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.\n\n### Reclaim\n\n\u003e armoria.herokuapp.com/claim/`name`/`coa`/`key`\n\nRaclaim 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.\n\n### Unclaim\n\n\u003e armoria.herokuapp.com/unclaim/`name`/`key`\n\nUnclaim removes the record from the database. For unclaim you need `name` and `key` (if was set on claim), but `coa` is not required.\n\n## Examples\n\nCoat of arms generated for seed `123456789`, rendered in `svg`, size is `400px`:\n\n\u003e [armoria.herokuapp.com/svg/400px/123456789](https://armoria.herokuapp.com/svg/400px/123456789)\n\nCoat of arms generated for seed `Armortown`, rendered in `png`, size is `800`px:\n\n\u003e [armoria.herokuapp.com/png/800/Armortown](https://armoria.herokuapp.com/png/800/Armortown)\n\nRandom coat of arms in `png`, size `200`px:\n\n\u003e [armoria.herokuapp.com/png/200](https://armoria.herokuapp.com/png/200)\n\nCoat of arms manually created in Armoria GUI, default format (`svg`) and size (`500px`):\n\n\u003e [armoria.herokuapp.com/?coa={\"t1\":\"semy_of_lozengePloye-sable-argent-small\",\"division\":{\"division\":\"perPale\",\"line\":\"straight\",\"t\":\"semy_of_mullet4-sable-argent-small\"},\"ordinaries\":[{\"ordinary\":\"mount\",\"t\":\"azure\"}],\"charges\":[{\"charge\":\"lymphad\",\"t\":\"or\",\"p\":\"e\",\"size\":1.7}]}](https://armoria.herokuapp.com/?coa={\"t1\":\"semy_of_lozengePloye-sable-argent-small\",\"division\":{\"division\":\"perPale\",\"line\":\"straight\",\"t\":\"semy_of_mullet4-sable-argent-small\"},\"ordinaries\":[{\"ordinary\":\"mount\",\"t\":\"azure\"}],\"charges\":[{\"charge\":\"lymphad\",\"t\":\"or\",\"p\":\"e\",\"size\":1.7}]})\n\nCoat of arms manually created in Armoria GUI, rendered in `png` with size `200`px:\n\n\u003e [armoria.herokuapp.com/?coa={\"t1\":\"semy_of_lozengePloye-sable-argent-small\",\"division\":{\"division\":\"perPale\",\"line\":\"straight\",\"t\":\"semy_of_mullet4-sable-argent-small\"},\"ordinaries\":[{\"ordinary\":\"mount\",\"t\":\"azure\"}],\"charges\":[{\"charge\":\"lymphad\",\"t\":\"or\",\"p\":\"e\",\"size\":1.7}]}\u0026format=png\u0026size=200](https://armoria.herokuapp.com/?coa={\"t1\":\"semy_of_lozengePloye-sable-argent-small\",\"division\":{\"division\":\"perPale\",\"line\":\"straight\",\"t\":\"semy_of_mullet4-sable-argent-small\"},\"ordinaries\":[{\"ordinary\":\"mount\",\"t\":\"azure\"}],\"charges\":[{\"charge\":\"lymphad\",\"t\":\"or\",\"p\":\"e\",\"size\":1.7}]}\u0026format=png\u0026size=200)\n\nClaim or reclaim name `test` (no password protection):\n\n\u003e [armoria.herokuapp.com/claim/test/{\"t1\":\"gules\",\"charges\":[{\"charge\":\"fusil\",\"t\":\"argent\",\"p\":\"e\",\"size\":1.5}],\"shield\":\"heater\"}](https://armoria.herokuapp.com/claim/test/{\"t1\":\"gules\",\"charges\":[{\"charge\":\"fusil\",\"t\":\"argent\",\"p\":\"e\",\"size\":1.5}],\"shield\":\"heater\"})\n\nClaim or reclaim name `test2` with password `secret123`:\n\n\u003e [armoria.herokuapp.com/claim/test2/{\"t1\":\"ermine-sable-or\",\"division\":{\"division\":\"chevronny\",\"t\":\"argent\"},\"shield\":\"spanish\"}/secret123](https://armoria.herokuapp.com/claim/test2/{\"t1\":\"ermine-sable-or\",\"division\":{\"division\":\"chevronny\",\"t\":\"argent\"},\"shield\":\"spanish\"}/secret123)\n\nUnclaim name `test2` using password `secret123`:\n\n\u003e [armoria.herokuapp.com/unclaim/test2/secret123](https://armoria.herokuapp.com/unclaim/test2/secret123)\n\n## License\n\nThe code is distributed under [MIT](https://opensource.org/licenses/MIT).\n\nSimple svg shapes and charges are self-made and available under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/). Complex charges are historical, svg renders are coming from [WappenWiki](http://wappenwiki.org) and available for non-commercial use under [CC3](https://creativecommons.org/licenses/by-nc/3.0/). Source info is added to svg files. All images are manually optimized by me.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazgaar%2Farmoria-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazgaar%2Farmoria-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazgaar%2Farmoria-api/lists"}