OAI-PMH

Overview & Intended Use

OAI-PMH provides a uniform, standards-based way to harvest ASCR metadata for indexing, link-resolving, and preservation workflows. Harvesters submit HTTP requests with a small set of verbs (Identify, ListSets, ListMetadataFormats, ListIdentifiers, ListRecords, GetRecord); responses are well-formed XML. We support broadly interoperable formats so that discovery services, library catalogs, and research repositories can keep their records current without scraping HTML or PDFs.

Note: If you operate a LOCKSS/CLOCKSS box, an institutional repository, or a commercial discovery layer, we are happy to coordinate test harvests and provide example requests.

Endpoint & Access

Our OAI-PMH base URL (baseURL) is available upon request to ensure stable integrations and to prevent automated probing. If you are configuring a harvester, contact the editorial office (see Contact) and share your IP/domain, preferred schedule, and metadata format. We will confirm the baseURL and any set specifications that fit your use case.

Supported Verbs

Verb Purpose Key parameters
Identify Repository identity and capabilities None
ListMetadataFormats Available formats (e.g., oai_dc, jats where enabled) identifier (optional)
ListSets Partitioning (e.g., journal sections, issues) None
ListIdentifiers Headers only (for lightweight crawling) from, until, metadataPrefix, set, resumptionToken
ListRecords Full records for harvesting Same as above
GetRecord Single record by identifier identifier, metadataPrefix

Metadata Formats

To balance broad interoperability with rich, domain-specific description, we support at least one baseline format and, where applicable, JATS XML for article-level metadata.

  • Dublin Core (oai_dc) — minimal, widely supported fields (title, creators, description/abstract, publisher, date, type, format, identifier, source, language, relation, coverage, rights).
  • JATS (jats) — richer article structure (contributors with roles, affiliations, abstracts by section, funding data, references, license information, clinical trial IDs). Availability depends on platform configuration.

Sets & Scoping

OAI-PMH sets allow harvesters to request subsets of the repository (e.g., by journal section or issue). Common patterns include a set for each Section (Original Research, Reviews, Case Reports) and for each Issue/Volume where the platform supports it.

  • Use ListSets first to enumerate available setSpecs.
  • Scope by date using from and until with day-level granularity (UTC).
  • Combine set scoping with metadataPrefix to minimize payloads.

Sample Requests

Resumption Tokens & Paging

Large result sets are split across multiple responses. The repository returns a resumptionToken with an optional size hint and expiration. Your harvester should:

  • Cache the last successful token and resume from there after any connectivity issues.
  • Avoid mixing parameters with a token (per the spec, pass only verb and resumptionToken).
  • Throttle follow-up requests (see Throttling).

Dates, Granularity & Time Zones

ASCR supports day-level granularity (YYYY-MM-DD). Timestamps in responses are UTC. If your pipeline runs more than once per day, include a one-day overlap in the from/until window to avoid missing updates made near midnight boundaries. If your system stores local times, normalize to UTC before constructing requests.

Deleted Records & Status Flags

OAI-PMH repositories signal record status in the header. While ASCR rarely removes records, updates can include corrections, retractions, or expressions of concern. We recommend:

  • Honor the status="deleted" flag if present (keep a tombstone or remove, per your policy).
  • Parse relation links in JATS (or provided fields) to interlink original articles with notices.
  • Prefer the DOI landing page for citation linking; use OAI identifiers for harvesting only.

Persistent Links & Licensing

Each article includes a DOI in canonical form (https://doi.org/…) and a clear license statement (typically CC BY 4.0). Preserve these fields during ingestion so your users see correct reuse permissions and stable links. If your discovery layer re-renders abstracts, retain the attribution and the license line.

Best Practices for Harvesters

Troubleshooting & Common Errors

Symptom Likely cause Resolution
HTTP 400 with badArgument Malformed parameters Check spelling, omit extra params when using resumptionToken.
Empty ListRecords response Date window too narrow; wrong metadataPrefix Broaden from/until; use ListMetadataFormats.
cannotDisseminateFormat Unsupported metadataPrefix Fall back to oai_dc or enable JATS in coordination with us.
HTTP 503 Retry-After Server throttle Honor Retry-After header; slow subsequent requests.
Missing references in DC DC is minimal Use JATS format where available for reference lists and funding data.

Security & Responsible Use

Respect the server and our users by following polite harvesting practices. Do not attempt to scrape PDFs through the OAI-PMH interface, and do not store email addresses or other non-public personal data beyond what is included in public metadata. If you operate a shared harvester, include a recognizable User-Agent string and a contact email so we can reach you about operational issues.

Frequently Asked Questions

Can I rely on OAI-PMH for full-text?

No. OAI-PMH transmits metadata. Follow the DOI or article URL for HTML/PDF. For text-and-data mining, see our Open Access Statement and repository guidance.

What should I index as the canonical link?

Use the DOI (if available) as the canonical link and render the journal landing page as the source of record. Keep the OAI identifier strictly for harvesting.

How often should I harvest?

Weekly works for most catalogs. If you display “early view” content or metrics dashboards, consider daily, incremental runs.

Do you provide Crossref metadata directly?

We register articles with Crossref; OAI-PMH complements that by providing a consolidated feed aligned with our site records. Many indexers merge OAI-PMH with Crossref and other sources.

Contact for Integrators

To request the baseURL, enable JATS, or coordinate a test harvest, contact: [email protected] · [email protected]

Last Updated: 2025-09-19 · Copyright & License: Page content is available under CC BY 4.0.