OAI-PMH
OAI-PMH is a widely-used standard for querying metadata, frequently used by libraries and repositories. We operate an OAI-PMH service for the distribution of metadata in XML format using the OAI-PMH version 2 repository framework.
On this page:
Quick start
See below for a description of the request parameters, including and explanation of sets an verbs. Please read that section if you are not familiar with OAI-PMH interfaces.
Public requests:
https://oai.crossref.org/oai?verb=ListSets
- To get get records deposited by a journal on a single day:
https://oai.crossref.org/oai?verb=ListIdentifiers&from=2025-03-07&until=2025-03-07&set=J:10.1371:60407
For Members:
- To get records registered for a title on a single day:
https://oai.crossref.org/DepositHarvester?verb=ListRecords&from=2020-01-01&until=2025-03-01&set=J:10.5555:161845&usr=email@address.com/role&pwd=password
- To get citation matches for a given day:
https://oai.crossref.org/oai?verb=ListRecords&usr=email@address.com/role&pwd=password&set=J:10.5555:161845&from=2025-03-01&until=2025-03-01&metadataPrefix=cr_citedby&include_postedcontent=false
For Metadata Plus subscribers:
Use the following header and your API token: Crossref-Plus-API-Token: Bearer [FullTokenHere] in all requests.
- To get a single metadata record:
https://oai.crossref.org/oai?verb=GetRecord&identifier=info:doi/10.1371%2Fjournal.pone.0021395
- To get metadata for one journal on a given day:
https://oai.crossref.org/oai?verb=ListRecords&from=2025-03-07&until=2025-03-07&set=J:10.1371:60407
Details
Authentication
Members can access the DepositHarvester endpoint by including their username and role in the usr field and their password in the password field.
Metadata Plus subscribers can use the verbs GetRecord and ListRecords on the oai endpoint by including the following header with their requests:
Crossref-Plus-API-Token: Bearer [API token]
We allow 3 concurrent initial OAI-PMH requests per user. There is no concurrency limit for follow-on requests (requests made with a resumption token).
Data sources
The OAI API does not include all records, only those that appear in a journal, book, or series. For example, posted content (including preprints) are not included. To access all metadata, we recommend using the REST API.
Responses are in an XML format. The available formats can be retrieved by making the following requests:
https://oai.crossref.org/oai?verb=ListMetadataFormats
https://oai.crossref.org/DepositHarvester?verb=ListMetadataFormats
The supported formats are:
Understanding sets and verbs
Two understand how to make requests, there are two important concepts: sets and verbs. We explain these before giving the request parameters below.
Sets
Requests depend on the concept of a ‘set’, which is a journal, book, conference series, or other item that contains content items and has a publication ID. Each set has a type: J for journals, B for books, conference proceedings, dissertations, reports, and datasets, and S for series.
The format for the set field is: [set type]:[doi_prefix]:[pub id] where
- Set type:,
J, B, or S. - doi_prefix is the prefix of the DOI, e.g. 10.64000.
- pub id is the [publication ID] of a set.
For example, J:10.1002:4 returns content in the journal Applied Organometallic Chemistry. The DOI prefix and publication ID are optional and can be omitted. If only the set is given, content in sets of the given type will be returned. If a set and a prefix are given, content matching the set and in the given prefix will be returned.
You can retrieve publication IDs from the title list. Click the ID logo next to the title in search results to see the ID.The UNIXSD output format also includes the journal-id (J) or book-id (B).
Verbs
The content of the response is defined by the verb parameter. Here is a summary of what each verb provides:
| Verb | Accessible by | Response |
|---|
ListSets | All users | List all sets included in the API. |
ListIdentifiers | All users | A list of DOIs satisfying the request criteria. |
ListMetadataFormats | All users | A list of all metadata formats the API delivers. |
GetRecord | Members (for their own content) and Metadata Plus subscribers (for all content) | A single metadata record. |
ListRecords | Members (for their own content) and Metadata Plus subscribers (for all content) | A list of metadata records satisfying the request criteria. |
Identify | All users | Provides details about the endpoint. |
Members can access information about their recent deposits using GetRecord and ListRecords with the DepositHarvester endpoint.
Endpoints
The base URL for requests is https://oai.crossref.org and there are two endpoints:
oai for general requests and retrieving metadata.DepositHarveter for members to retrieve their deposited metadata.
OAI
The endpoint is located at https://oai.crossref.org/oai. The following parameters can be used with all verbs:
| Parameter name | Possible values (red) and examples (black) | Description |
|---|
usr | example@email.com/my_role | Crossref member email address and role. Required for metadataPrefix=cr_citedby. |
pwd | my_password | Crossref member password. Required for metadataPrefix=cr_citedby. |
metadataPrefix | cr_unixsd, cr_unixsd, cr_citedby | The output format. cr_citedby returns forward links (for members only). |
verb | ListSets, ListIdentifiers, ListMetadataFormats for metadata Plus subscribers: GetRecord, ListRecords, Identify | The type of request being made. |
Additional parameters with the ListSets verb:
| Parameter name | Description |
|---|
resumptionToken | For large responses, use the resumptionToken in the previous response to retrieve the next page of responses. Note that the total number of items is also in the resumptionToken field of the response. |
Additional parameters with the ListIdentifiers and ListRecords verbs:
| Parameter name | Possible values (red) and examples (black) | Description |
|---|
metadataPrefix | cr_unixsd, cr_unixsd, cr_citedby (members only) | The output format. |
set | S, B:10.64000, or J:10.1002:4. | Set for the items. See above for an explanation. Used for ListIdentifiers and ListRecords |
identifier | info:doi/10.1101%2Fgr.3760605 | DOI for record to return (for verb=GetRecord only) |
from | YYYY-MM-DD | Returns records updated on or after this date. |
until | YYYY-MM-DD | Returns records updated on or before this date. |
resumptionToken | | For large responses, use the resumptionToken in the previous response to retrieve the next page of responses. Note that the total number of items is also in the resumptionToken field of the response. |
includePostedContent | True, False (default) | Only for members retrieving forward links. Includes forward links from posted content items, e.g. preprints. |
Additional parameters with the GetRecord verb:
| Parameter name | Possible values (red) and examples (black) | Description |
|---|
identifier | info:doi/10.1101%2Fgr.3760605 | DOI for record to return (for verb=GetRecord only) |
DepositHarvester
The endpoint is located at https://oai.crossref.org/DepositHarvester and is available to Crossref members only. It takes the same arguments for ListRecords and GetRecord as the oai endpoint.
Using metadataPrefix=cr_citedby retrieves forward links, however we recommend using other methods to retrieve forward links because the OAI-PMH API does not contain all content items and therefore does not include all references.
