# CANOA — Corpus Apertum Nummorum Orbis Antiqui
> CANOA is an open corpus (catalog) of ancient world coinage: Greece, Rome, Persia, Carthage and other civilizations. Open data, images and scholarly coin descriptions.
Main site: https://canoanumis.org/.
Contacts: suggestions — info@canoanumis.org; complaints — abuse@canoanumis.org.
Cookies/tracking: for humans, consent is confirmed by the banner button (cookie canoa_consent) or by continuing to use the site; for bots and crawlers, consent to cookies and anonymized analytics (Yandex.Metrika) is presumed upon access.
## Main sections
- [Coin catalog](https://canoanumis.org/search/): coin cards with metrology, dating, mints and images
- [Regions and civilizations](https://canoanumis.org/map/): regions and civilizations (via the mint map)
- [Mints](https://canoanumis.org/mints/): directory of minting places with a map
- [Museums](https://canoanumis.org/museums/): holding museums (collection codes), their specimens, licences and coin types represented
- [About](https://canoanumis.org/about/): mission, licenses (coin types — ODbL, images — © museums), citation guidelines
## Data
- API and exports: open catalog dumps in JSON/CSV
- [Rights manifest](https://canoanumis.org/licenses.json) — machine-readable licence mapping for every dataset and collection code, with aliases, scope (metadata/media) and version. The complete collections_index comes first, so even a truncated read contains every code, its licence and the redistributable flag
- Rights manifest, chunked (for readers with a response-size limit): /licenses/collections.json?page=1&per_page=25 (paged, max 50, returns total/total_pages/next/prev), /licenses/collections/<code>.json (one collection), /licenses.jsonl (NDJSON, one record per line), /licenses.json?view=index (compact index only)
- [Full dump](https://canoanumis.org/dumps/index.json) — complete gzipped JSONL export (coin types, specimens, hoards, mints, authorities) with record counts, sizes and SHA-256 checksums; every file has a mirror
## API (JSON)
- GET https://canoanumis.org/api/search?q=<query> — search rulers, mints and denominations. Example: /api/search?q=Nero
- GET https://canoanumis.org/api/coins — coin list with filters: q, authority, mint, denomination, material, dataset, has_image (1 = types with photos, 0 = all; omitted = all types here — the /search/ page defaults to photos only), date_from, date_to, sort (name | -name | date | -date | specimens | -specimens; specimens — most common first), page, per_page. Every item has specimen_count. Example: /api/coins?authority=http://nomisma.org/id/nero&mint=36 (36 = Rome); add &format=html for a simple JS-free HTML list
- GET https://canoanumis.org/api/coins/<slug>/ — coin card by slug (from /api/coins). Example: /api/coins/ric-i-second-edition-nero-1/
- GET https://canoanumis.org/api/coin/<id>/ — coin card by numeric id. Example: /api/coin/168481/
- GET https://canoanumis.org/api/filter-options?field=mint|authority|denomination|material — filter values (mint returns numeric ids)
- GET https://canoanumis.org/api/mints.geojson — mints as GeoJSON
- GET https://canoanumis.org/api/hoards — hoards in a region, bbox filter: lat_min, lat_max, lon_min, lon_max (+ q, dataset, page, per_page). Example: /api/hoards?lat_min=36.5&lat_max=38.5&lon_min=12&lon_max=16
- GET https://canoanumis.org/api/hoards/<id>/ — hoard detail with coin types (authority, mint, dates)
- GET https://canoanumis.org/api/authorities — full list of rulers/emperors with type counts (q, has_types, page/per_page)
- GET https://canoanumis.org/api/authorities/<id>/ — ruler detail + his coin types (paged)
- GET https://canoanumis.org/api/mints — full list of mints with coordinates and type counts
- GET https://canoanumis.org/api/regions — regions/civilizations with type counts
- GET https://canoanumis.org/api/dies — coin dies (Roman Republican Die Project); filters q, die_type
- GET https://canoanumis.org/api/denominations, /api/materials — full reference lists with type counts
- GET https://canoanumis.org/api/stats — catalog statistics (types, specimens, hoards, mints, authorities...)
- GET https://canoanumis.org/api/coins/<id>/specimens — museum specimens of a coin with metrics: weight, diameter, axis, collection
- GET https://canoanumis.org/api/coins?hoard_id=<id> — coin types of a specific hoard
- GET https://canoanumis.org/api/crawlers — crawler/bot traffic statistics for a period: days (1 up to available history, default 7) or from/to (YYYY-MM-DD); categories, HTTP codes, top paths/IPs/user agents; API breakdown: api_categories (who requests /api/*), api_endpoints (numeric ids collapsed to {id}), api_ips, api_user_agents
- GET https://canoanumis.org/banner/<slug>/ — coin banner page (preview and embed codes); PNG: /banner/<slug>/<WxH>.png and <WxH>-light.png (6 sizes × 2 themes)
- GET https://canoanumis.org/api/collections — public user collections (id, owner, title, item counts)
- GET https://canoanumis.org/api/collections/<owner>/<slug>/ — collection detail: items with catalog coin_type refs (or unattributed), weight/diameter/axis, photo thumbnails
User collections are private by default: /collections/my/, /api/my/* and secret unlisted links (/collections/u/...) are closed to crawlers — do not attempt to access them.
The API and pages return only images that actually exist: if a file is lost (PAS/Gallica), the image field is empty — do not request dead URLs.
URL artifacts: paths ending in /null (also /undefined, /NaN) are not real pages — some crawlers compose them by appending a null value to a page path (validated: meta-externalagent/1.1). The site answers 301 to the clean URL (permanent redirect): use the clean address instead of these variants.
API rate limits: 30 req/s per IP with burst 90 at the edge (nginx) and 120 requests/min per IP for /api/* (app side); when exceeded you get 429 with Retry-After: 60 — honour it and slow down instead of retrying in a loop. For bulk harvesting prefer /api/coins?per_page=100 with pauses, and check /api/crawlers to see your own traffic.
authority/denomination/material values are URIs (e.g. http://nomisma.org/id/nero), mint is a numeric id from /api/filter-options?field=mint, date_from/date_to are years (e.g. 54 and 68 for Nero's reign).
## Searching coins (example for LLM agents)
1. /api/search?q=Nero → find a result of type ruler with uri=http://nomisma.org/id/nero
2. /api/filter-options?field=mint → find the id of the mint you need (e.g. Rome = 36)
3. /api/coins?authority=http://nomisma.org/id/nero&mint=36&per_page=100 → JSON list of coins with fields id, slug, label, mint, dates and url (/coins/<slug>/).
A period can be given without authority: /api/coins?date_from=54&date_to=68&mint=<id> — coins struck during Nero's reign (54–68) in Rome.
## For agents
- [Full documentation](https://canoanumis.org/llms-full.txt) — data model, full API reference, examples
- [Instructions for agents](https://canoanumis.org/agents.md) — workflow, citation rules, license constraints
- [Instructions for Hermes Agent](https://canoanumis.org/hermes.md) — specialized guide (Nous Research)
- [Skills for working with the API](https://github.com/canoa-dev/canoa-skills) — ready-made skills (Agent Skills / Hermes): canoa-api (endpoints, recipes, data export), canoa-hoard-analysis (regional hoard analysis → coin distribution by emperors/periods → charts → PDF article). Install: `npx skills add canoa-dev/canoa-skills`
- [robots.txt](https://canoanumis.org/robots.txt) — explicit allow rules for named crawlers and agents (GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-SearchBot, Claude-User, PerplexityBot, CCBot, Google-Extended, Amazonbot, Applebot, bingbot, YandexBot and others)
- [/edu/](https://edu.canoanumis.org/) — Canoa // edu: ancient coins for schools (LMS assignments, LTI 1.3). Public pages are indexed: /edu/, /edu/curriculum/ (+5 tracks), /edu/lesson-plans/ (+lesson plans), /edu/demo/, /edu/how-it-works/, /edu/pricing/, /edu/for-districts/, /edu/for-homeschool/, /edu/faq/, /edu/contact/, /edu/accessibility/, /edu/legal/*; /edu/assignment/*, /edu/my/, /edu/teacher/*, /edu/lti/* are closed to automated access (anti-cheating)
# CANOA — Corpus Apertum Nummorum Orbis Antiqui (full documentation)
## About
CANOA is an open corpus of ancient world coinage: Greece, Rome, Persia, Carthage, Byzantium and other civilizations.
The catalog combines: coin types (128,520), physical specimens from museum collections (540,000+), hoards (9,833), dies (17,074), mints (2,613).
Type data — ODbL (numismatics.org); images belong to the holding museums and are used under their licenses (many are non-commercial only).
## Data model
- CoinType: id, slug, uri, label (pref_label), ocre_id (catalog number, e.g. ric.1(2).ner.1), mint, authority, denomination, material, start_date/end_date (dating), obverse/reverse legend and description, obverse_image/reverse_image (URL), url (/coins/<slug>/).
- Specimen: a physical coin from a museum collection, linked to a CoinType; fields weight, diameter, axis, collection.
- Mint: name, label_ru, latitude/longitude.
- Authority: label, label_ru, uri (nomisma.org).
- Hoard, Die: separate reference books.
## API (JSON) — full reference
### /api/search?q=<query>
Search across rulers, mints, denominations and coins. Response: {results: [{type: ruler|mint|denomination|coin, label, label_ru, uri, count, url}]}.
Example: /api/search?q=Nero → ruler Nero (uri http://nomisma.org/id/nero, count 622, url /search/?authority=http://nomisma.org/id/nero).
### /api/coins
Coin list (CoinType) with filters. Response: {count, page, num_pages, per_page, results: [{id, slug, uri, label, ocre_id, mint, mint_id, authority, authority_uri, denomination, material, date_from, date_to, url, image, specimen_count}]}.
Parameters:
- q — text search (AND tokens over label/ocre_id/legends)
- authority, denomination, material — URIs (e.g. http://nomisma.org/id/nero)
- mint — numeric id (from /api/filter-options?field=mint)
- dataset — dataset identifier (ocre, crro, pella, iris, mkrf, ...)
- has_image — 1 (with images only) / 0 (all); if omitted, the API returns all types — note the web search page (/search/) defaults to types with photos instead
- date_from, date_to — years: coins whose period intersects the range
- sort — name | -name | date | -date | specimens | -specimens (specimens: most common first; -specimens: least common first)
- page, per_page (max 100)
- specimen_count — number of museum specimens of the type; sort=specimens&per_page=1 gives the catalog's most common coin.
Images: the image field contains a URL only if the file really exists; lost sources (Gallica, PAS) return an empty string — do not request such URLs.
- format — json (default) or html: /api/coins?authority=nero&mint=rome&format=html — the same list, but a simple HTML page without JavaScript (only links to /coins/<slug>/, pagination)
Example: /api/coins?authority=http://nomisma.org/id/nero&mint=36&per_page=100 — Nero's coins from Rome.
Period example: /api/coins?date_from=54&date_to=68&mint=36 — coins of Rome 54–68 CE.
### /api/coins/<slug>/
Coin card by slug (from /api/coins). Example: /api/coins/ric-i-second-edition-nero-1/.
Response: id, slug, label, ocre_id, definition, mint, mint_id, authority(+ru), denomination(+ru), material(+ru), manufacture, date_from, date_to, obverse/reverse legend and description, obverse_image/reverse_image (URL), source, uri, url.
### /api/coin/<id>/
Coin card by numeric id. Example: /api/coin/168481/.
Response: as /api/coins/<slug>/ plus specimen_count and specimens_url.
### /api/coins/<id>/specimens
Museum specimens of a coin with metrical data. Response: {coin_id, coin_label, count, page, num_pages, results: [{id, identifier, collection, weight, diameter, axis, findspot, obverse_image, reverse_image, specimen_url}]}.Each item has specimen_url (/api/specimens/<id>/) — a direct link to the individual specimen card, which mirrors the original collection record (finds.org.uk, British Museum, ...).
Example: /api/coins/168481/specimens. Useful for metrology studies (weight/diameter distributions per type).
### /api/specimens/<id>/Individual museum specimen card by id (from /api/coins/<id>/specimens, field specimen_url). Response: {id, identifier, collection, coin_type: {id, label, slug, url}, uri, weight, diameter, axis, findspot, obverse_image, reverse_image}.Use as a direct machine-readable mirror of an external collection record (e.g. https://finds.org.uk/database/artefacts/record/id/197163 ↔ /api/specimens/732453/).
### /api/hoards
Hoard list. Filters: lat_min/lat_max/lon_min/lon_max (bounding box by findspot coordinates), q (label), dataset, page/per_page (max 100).
Response: {count, num_pages, page, results: [{id, label, dataset, findspot, latitude, longitude, coin_count, type_count, start_date, end_date, url}]}.
Example: /api/hoards?lat_min=36.5&lat_max=38.5&lon_min=12&lon_max=16 — hoards of Sicily.
### /api/hoards/<id>/
Hoard detail with its coin types. Response: {id, label, dataset, findspot, latitude, longitude, coin_count, type_count, start_date, end_date, coin_types: [{id, label, ocre_id, authority, authority_uri, mint, mint_id, date_from, date_to, url}]}.
### /api/authorities
Full list of rulers/emperors with type counts. Filters: q (label/label_ru), has_types (default 1), page/per_page (max 100).
Response: {count, num_pages, page, results: [{id, label, label_ru, uri, type_count, url}]}.
### /api/authorities/<id>/
Ruler detail + his coin types (paged). Response: {id, label, label_ru, uri, definition, type_count, page, num_pages, results: [{id, label, ocre_id, mint, denomination, material, date_from, date_to, url}]}.
### /api/mints
Full list of mints with coordinates and type counts. Filters: q (name), has_types (default 1), page/per_page.
Response: {count, num_pages, page, results: [{id, name, latitude, longitude, slug, type_count, uri, url}]}.
### /api/museums
Museum directory: holding museums (Specimen.collection codes) with specimen and coin-type counts, licence label and URL. Response: {count, results: [{code, label, label_ru, specimens, coin_types, licence, licence_url, url}]}. Example: /api/museums
### /api/museums/<code>/
One museum with the coin types it holds (paged). Response: {code, label, label_ru, specimens, coin_types, licence, licence_url, count, page, num_pages, per_page, results: [{id, slug, label, ocre_id, dataset, date_from, date_to, specimens_here, url}]}. If a museum has specimens not yet linked to coin types (e.g. ans), coin_types is 0 and note explains it. Example: /api/museums/bm/?per_page=50
### /api/regions
Regions/civilizations (dataset groups) with type counts. Response: {count, results: [{dataset, label_ru, label_en, type_count, url}]}.
### /api/dies
Coin dies (Roman Republican Die Project). Filters: q (label), die_type (obverse/reverse), page/per_page.
Response: {count, num_pages, page, results: [{id, label, notation, die_type, dataset, coin_type_id, coin_label, image}]}.
### /api/denominations, /api/materials
Full reference lists with type counts. Response: {count, results: [{id, label, label_ru, uri, type_count}]}.
### /api/stats
Catalog statistics for articles and citation. Response: coin_types, coin_types_with_photo, specimens, specimens_with_photo, hoards, hoards_geolocated, mints, authorities, denominations, materials, dies, findspots, datasets, generated_at.
### /api/coins?hoard_id=<id>
The hoard_id filter returns the coin types of a specific hoard (same response as /api/coins).
### /api/crawlers
Crawler/bot traffic statistics (public — for bot operators planning their crawls). Parameters: days (1 up to available history, default 7) or from/to (YYYY-MM-DD, overrides days).
Response: {period: {from, to, days}, total_requests, api_requests, site_requests, api_share, categories: {name: {requests, share}}, codes: {code: count}, top_paths, top_paths_404, top_paths_5xx, top_ips, top_user_agents, api_categories, api_endpoints, api_ips, api_user_agents}.
Top paths / IPs / user agents are aggregated over the WHOLE requested period (all selected days), not just the last day; per-day data is capped at 200 keys, so a very long tail can be truncated.
Example: /api/crawlers?days=7 — bot traffic for the last week.
### Rate limits
The API is rate limited per IP: 30 req/s with burst 90 at the edge (nginx) and 120 requests/min for /api/* (app side). Over the limit the response is 429 with Retry-After: 60 — honour the header and back off instead of retrying in a tight loop. For bulk harvesting use per_page=100 (max) with pauses; /api/crawlers is subject to the same limits.
### /api/collections (user collections)
Public user collections (personal coin cabinets linked to the catalog).
- GET /api/collections — list of public collections. Response: {collections: [{id, owner, owner_slug, title, slug, description, visibility, item_count, attributed_count, updated_at, url}]}.
- GET /api/collections/<owner>/<slug>/ — collection detail with items. Response: {…collection fields…, items: [{id, status (attributed|unattributed), weight, diameter, axis, coin_type: {id, slug, uri, label, url} | null, photos: [thumbnail urls]}]}.
- GET /api/collections/u/<token>/ — the same detail for an unlisted collection by its secret link token.
Private data is NOT exposed: /collections/my/, /api/my/collections (owner-only, requires session or ?api_key=<Profile.api_token>) and secret links are excluded from robots.txt; do not attempt to access them.
## Canoa // edu (/edu/) — schools section
- /edu/ — Canoa // edu landing: coin assignments for LMS (Canvas, Schoology, Moodle) via LTI 1.3.
- Public pages: /edu/ (landing), /edu/curriculum/ and /edu/curriculum/<track>/ (curriculum tracks: ap-latin, world-history, classical-civ, hoard-analysis, ai-research-agent), /edu/lesson-plans/ and /edu/lesson-plans/<slug>/ (free lesson plans; PDF — /edu/lesson-plans/<slug>.pdf), /edu/demo/ (demo assignment without registration), /edu/how-it-works/ (LTI guides for Canvas/Schoology/Moodle), /edu/pricing/, /edu/for-districts/, /edu/for-homeschool/, /edu/faq/, /edu/contact/, /edu/accessibility/ and /edu/accessibility/acr.html, /edu/legal/privacy/, /edu/legal/terms/, /edu/legal/ndpa/, /edu/legal/dpa/, /edu/legal/subprocessors/, /edu/legal/data-deletion/, /edu/legal/ny-parents-bill-of-rights/.
- Closed paths (only via an LTI session from the LMS, anti-cheating — do not bypass): /edu/assignment/*, /edu/my/, /edu/teacher/*, /edu/lti/*.
- LTI 1.3: /edu/lti/login/, /edu/lti/launch/, /edu/.well-known/jwks.json. The module does not store student personal data (only opaque sub); coin images are not copied.
## Citation
- Every coin page: COinS (Zotero), citation_* meta tags (Google Scholar),
RIS/BibTeX/CSL-JSON export (/coins/<slug>/cite/<fmt>/). Guidelines: https://canoanumis.org/cite/.
## URL artifacts (do not crawl)
Some crawlers compose URLs by appending a null value to a page path, producing paths like /search/null, /coins/<slug>/null, /banner/<slug>/null, /regions/<slug>/null, /mints/<slug>/null (validated: meta-externalagent/1.1, Sept 2026, ~115k requests). These pages do not exist and never existed: the site never emits the token "null" in HTML, sitemaps, robots.txt or headers. The site answers 301 to the clean URL (the artifact segment is dropped). Do not request these variants: use the clean URL, the API and /sitemap.xml instead.
## Coin banners (for third-party sites)
- /banner/<slug>/ — HTML banner page: preview of all sizes and embed codes (HTML/Markdown/BB-code).
- /banner/<slug>/<WxH>.png — dark theme; <WxH>-light.png — light theme. Sizes: 970x90, 728x90, 468x60, 320x50, 300x600, 160x600. Cache-Control: max-age=86400.
- Banners: coin image, name, catalog number, dates·mint·ruler, CANOA brand; images — © holding museums.
- /banner/ pages are absent from the sitemap — do not index them.
