API endpoint: resolve.php

Endpoint slouží pro dohledání skenu stránky podle tištěného čísla stránky napříč podporovanými zdroji.

Podporované typy vstupů

Poznámka: API podporuje také vstup Wikidata QID (Q12345) nebo URL položky (https://www.wikidata.org/wiki/Q12345). Resolver postupně zkouší dostupné vlastnosti dle priority chainu.

Poznámka k ANNO přes Wikidata: samotné P9258 nestačí pro konkrétní číslo periodika; pokud chce klient přes Wikidata resolver použít ANNO, musí v requestu dodat pole date ve formátu YYYYMMDD nebo YYYY-MM-DD, ze kterého se složí issue URL anno.onb.ac.at.

Prosté číslo bez prefixu: Prosté číslo bez specifikace zdroje se neakceptuje samostatně (brání nejasnostem mezi Frankfurt, Wienbibliothek a dalšími); je třeba zadat URL, URN, OAI identifikátor nebo Wikidata QID.

OAI identifikátory: OAI identifikátory jsou podporovány pro:

• Wienbibliothek Digital (oai:www.digital.wienbibliothek.at:{id})
• SBC Wrocław (oai:www.sbc.org.pl:{id})

Omezení URN:

• NBN URN (urn:nbn:...) jsou plně podporovány přes nbn-resolving.org

URL a metoda

• URL: /sourcepage/api/resolve
• Metoda POST: API lookup endpoint (Content-Type: application/json)
• Metoda GET bez query parametrů a bez body: vrátí tuto dokumentaci v HTML podobě

Poznámka: GET s query parametry nebo s body není podporován a vrací 405.

Request body

Příklad requestu:

{
  "input": "Q18029632",
  "page": "24",
  "date": "1898-09-22"
}

Úspěšná odpověď

HTTP status: 200

{
  "ok": true,
  "status": 200,
  "input": "Q18029632",
  "date": "18980922",
  "results": [
    {
      "source_type": "anno.onb.ac.at",
      "resolved_input": "https://anno.onb.ac.at/cgi-content/anno?aid=wsb&datum=18980922",
      "resolver_chain": ["wikidata", "P9258"],
      "identifier": "wsb:18980922",
      "page_number": "24",
      "leaf_num": null,
      "iiif_image_url": "https://iiif.onb.ac.at/images/ANNO/wsb18980922/.../full/full/0/default.jpg",
      "iiif_canvas_url": "https://iiif.onb.ac.at/presentation/ANNO/wsb18980922/canvas/...",
      "iiif_canvas_id": "https://iiif.onb.ac.at/presentation/ANNO/wsb18980922/canvas/...",
      "viewer_url": "https://anno.onb.ac.at/cgi-content/anno?aid=wsb&datum=18980922&seite=24&zoom=100",
      "manifest_url": "https://iiif.onb.ac.at/presentation/ANNO/wsb18980922/manifest",
      "page_numbers_url": null,
      "source_title": "...",
      "source_date": "...",
      "source_external_identifier": "..."
    }
  ]
}

Význam hlavních polí

Pole v results[]:

PDF zdroje (SBC)

Pro doménu sbc.org.pl endpoint používá režim PDF pipeline:

1. Stáhne PDF dokument a uloží jej na 14 dní.

2. Extrahuje OCR textovou vrstvu a sestaví trvalý JSON page index.

3. Rozdělí PDF na obrázky po stránkách a ukládá je na 14 dní.

4. Vrátí document_url (SBC dokument) a image_download_url (lokální extrahovaný obrázek).

Poznámka: první request nad novým PDF dokumentem může běžet déle. Frontend proto zobrazuje průběžné stavové hlášky.

Poznámka: mapování page -> PDF stránka je best-effort podle OCR, ale pro číselné stránky se nad OCR kandidáty dopočítává nejpravděpodobnější spojitá řada. Při nenalezení přesného mapování je zdroj vrácen jako partial.

ÖNB IIIF

Detailní dokumentace k ÖNB IIIF je v samostatném souboru:

• ../docs/onb-iiif.md

Chybová odpověď

{
  "ok": false,
  "error": "Tištěná stránka nebyla v dokumentu nalezena.",
  "error_code": "printed_page_not_found",
  "status": 404
}

Pole chybové odpovědi

Běžné error_code

HTTP status kódy

Příklady volání

curl -sS -X POST 'https://tools.daelba.eu/sourcepage/api/resolve' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"input":"https://archive.org/details/gothaischerhofka00unse/page/n126/mode/2up","page":"24"}'

curl -sS -X POST 'https://tools.daelba.eu/sourcepage/api/resolve' \
  -H 'Content-Type: application/json' \
  -d '{"input":"urn:nbn:de:bvb:12-bsb10917624-5","page":"3"}'

curl -sS -X POST 'https://tools.daelba.eu/sourcepage/api/resolve' \
  -H 'Content-Type: application/json' \
  -d '{"input":"Q65682037","page":"3"}'