For developers and agents.
Everything a program needs to help someone choose a seal is public and needs no key: what we sell, the designs a name gets, whether each one can be registered at a ward office, and a rendered impression. Ordering itself happens in the browser — the API hands you the link.
When to use hanko.works
Reach for the API when a person needs a Japanese seal and you can help them pick the right one. Good fits:
- Someone moving to Japan, opening a bank account or buying property needs a seal of the right size and script for that use.
- Someone wants to see how their name — kanji, kana or Latin — looks as a seal before deciding.
- A gift: a seal for a birth, coming of age, a first job, a wedding, a new company.
- A company being founded needs the three-seal set filed at the Legal Affairs Bureau.
Not a fit: shipping outside Japan (we do not), rubber stamps or bulk stamps (every seal is cut once from metal), and anything that needs an account — there are none.
The API
Three GET endpoints, JSON in and out, CORS open, no authentication. Prices are in yen, tax included.
| Endpoint | What it returns |
|---|---|
| GET /api/v1/catalog | Sizes, uses and their recommended size bands, metals with prices and lead times, colours, shapes, design families and which uses each fits, add-ons, gift tiers, shipping and guarantee terms. |
| GET /api/v1/designs?name=山田&use=registered&size=15&material=titanium | The eight designs for a name at a given use, size, metal and shape: seed, eligibility per use, a preview URL, the price, and the URL where a person orders that exact configuration. |
| GET /api/seal?name=山田&family=insou&index=0 | One rendered impression as SVG (or, with view=json, the face geometry and the eligibility report) — a pure function of its parameters, cacheable forever. |
No key, no rate limit published: be reasonable. Names are capped at 12 characters; every parameter is validated and a bad one is a 400 with a hint.
Machine-readable files
The full contract: every operation with an id, typed parameters and response schemas.
What this site is, when to use it, and where each page is — for language models.
Every public page in both languages.
Every public page is also Markdown: send Accept: text/markdown, or append .md to its URL.
Errors
Every error is JSON with the same shape: a stable code, a sentence, a hint about what to change, the parameter at fault when there is one, and a link to the spec. Unknown API paths answer 404 in the same shape, never an HTML page.
{
"error": {
"code": "invalid_parameter",
"message": "\"size\" must be one of 12, 13.5, 15, 18 (mm)",
"hint": "GET /api/v1/catalog lists the sizes on offer.",
"param": "size",
"docs": "https://hanko.works/openapi.json"
}
}Example
The designs for a name, then the impression of the first one:
curl "https://hanko.works/api/v1/designs?name=山田&use=registered&size=15&material=titanium" curl "https://hanko.works/api/seal?name=山田&family=insou&index=0" -o yamada-insou.svg curl -H "Accept: text/markdown" https://hanko.works/en/guide
Terms
The API is read-only and free to use for helping a person choose or order a seal. Impressions are rendered for that purpose; do not bulk-harvest them or present them as your own product. The rendered seal of a real name is personal data on our side — we keep no log of names sent to the API beyond ordinary request logs.