# 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}]}.
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, ...)
- has_image — 1 (with images only) / 0 (all)
- date_from, date_to — years: coins whose period intersects the range
- sort — name | -name | date | -date
- page, per_page (max 100)
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}]}.
Example: /api/coins/168481/specimens. Useful for metrology studies (weight/diameter distributions per type).

### /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/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).

## 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/.
## 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, 320x100, 320x50. 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.