sample & added examples with filtersSee the document, CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies, for background.
- -The API described here is in alpha. If you encounter problems with the API or the documentation, please report them to:
- -
The API is generally RESTFUL and returns results in JSON.
- -The API will only work for CrossRef DOIs. You can test the registration agency for a DOI using the following convention:
- -http://doi.crossref.org/doiRA/{doi}
So testing the following CrossRef DOI:
- -10.1037/0003-066X.59.1.29
Will return the following result:
- -[
- {
- DOI: "10.1037/0003-066X.59.1.29",
- RA: "CrossRef"
- }
-]
-If you use any of the API calls listed below with a non-CrossRef DOI, you will get a 404 HTTP status response with the message “non-CrossRef DOI.”
All results are returned in JSON. There are two general types of results:
- -The mime-type for API results is application/vnd.crossref-api-message+json
Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
- -Lists results can contain multiple entries. Searching or filtering typically returns a list result. A list has two parts:
- -Note that the “message-type” returned will differ from the mime-type. There are six message-types:
- -Normally, and API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero.
- -If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
- -Major resource components supported by the CrossRef API are:
- -These can be used alone like this
- -| resource | -description | -
|---|---|
/works |
- returns a list of all works (journal articles, conference proceedings, books, components, etc), 20 per page. | -
/funders |
- returns a list of all funders in the FundRef Registry | -
/publishers |
- r eturns a list of all publishers. | -
Resource components can be used in conjunction with identifiers to retrieve the metadata for that identifier.
- -| resource | -description | -
|---|---|
/works/{doi} |
- returns metadata for the specified CrossRef DOI. | -
/funders/{funder_id} |
- returns metadata for specified funder and its suborganizations | -
/publishers/{owner_prefix} |
- returns metadata for the specified publisher. | -
Resource components can be combined to narrow down selections.
- -| resource | -description | -
|---|---|
/works/{doi}/funders |
- returns list of funders associated with the specified CrossRef DOI |
-
/funders/{funder_id}/works |
- returns list of works associated with the specified funder_id |
-
/publishers/{owner_prefix}/works |
- returns list of works associated with specified owner_prefix |
-
Parameters can be used to query, filter and control the results returned by the CrossRef API. They can be passed as normal URI parameters or as JSON in the body of the request.
- -| parameter | -description | -
|---|---|
query |
- limited DisMax query terms | -
filter={filter_name}:{value} |
- filter results by specific fields | -
rows={#} |
- results per per page | -
offset={#} |
- page offset | -
sample={#} |
- return random N results | -
http://api.crossref.org/funders/100000015/works?query=electron+pairs&filter=has-orcid:true&rows=1
-Note that if you include a body in your GET request, any URI parameters will be ignored. In short, you cannot mix URI parameters and JSON queries.
To use the API using JSON, pass the JSON in the body of the HTTP GET request like this:
- -curl -X GET -H "Content-Type: application/json" -d '{"query": "psychoceramics", "offset": 40, "rows": 20, "filter": {"has-orcid": true, "publisher": "10.5555"}}' http://api.crossref.org/works
-Queries support a subset of DisMax, so, for example you can refine queries as follows.
- -Works that include “renear” but not “ontologies”
- -http://api.crossref.org/works?query=renear+-ontologies
-or using JSON
- -curl -X GET -H "Content-Type: application/json" -d '{"query": "renear -ontologies"}' http://api.crossref.org/works
-Filters allow you to narrow queries. All filter results are lists. The following filters are supported:
- -| filter | -possible values | -description | -
|---|---|---|
funder |
- {funder_id} |
- metadata which include the {funder_id} in FundRef data |
-
publisher |
- {owner_prefix} |
- metadata belongs to published identified by {owner_prefix} (e.g. 10.1016 ) |
-
from-update-date |
- {date} |
- metadata updated since (inclusive) {date} |
-
until-update-date |
- {date} |
- metadata updated before (inclusive) {date} |
-
from-pub-date |
- {date} |
- metadata where published date is since (inclusive) {date} |
-
until-pub-date |
- {date} |
- metadata where published date is before (inclusive) {date} |
-
has-license |
- - | metadata that includes any <license_ref> elements. |
-
license.uri |
- {uri} |
- metadata where <license_ref> value equals {uri} |
-
license.content-version |
- {string} |
- metadata where the <license_ref>’s applies_to attribute is {string} |
-
license.max-embargo-days |
- {integer} |
- metadata where difference between publication date and the <license_ref>’s start_date attribute is <= {integer} |
-
has-full-text |
- - | metadata that includes any full text <resource> elements. |
-
fulltext.content-version |
- {string} |
- metadata where <resource> element’s content_version attribute is {string}. |
-
fulltext.content-type |
- {mime_type} |
- metadata where <resource> element’s content_type attribute is {mime_type} (e.g. application/pdf). |
-
public-references |
- - | metadata where publishers allow references to be distributed publically. | -
has-archive |
- - | metadata which include name of archive partner[1] | -
archive |
- {string} |
- metadata which where value of archive partner is {string}[1] |
-
has-orcid |
- - | metadata which includes one or more ORCIDs | -
orcid |
- {orcid} |
- metadata where <orcid> element’s value = {orcid} |
-
The prefix of a CrossRef DOI does NOT indicate who currently owns the DOI. It only reflects who originally registered the DOI. CrossRef metadata has an owner_prefix element that records the current owner of the CrossRef DOI in question.
- -Note that dates in filters should always be of the form YYYY-MM-DD. Also not that date information in CrossRef metadata can often be incomplete. So, for example, a publisher may only include the year and month of publication for a journal article. For a monograph they might just include the year. In these cases the API selects the earliest possible date given the information provided. So, for instance, if the publisher only provided 2013–02 as the published date, then the date would be treated as 2013–02–01. Similarly, if the publisher only provided the year 2013 as the date, it would be treated at 2013–01–01.
You can control the delivery and selection results using the rows, offset and sample parameters.
Normally, results are returned 20 at a time. You can control the number of results returns by using the rows parameter. To limit results to 5, for example, you could do the following:
http://api.crossref.org/works?query=allen+renear&rows=5
-If you would just like to get the summary of the results, you can set the rows to 0 (zero).
http://api.crossref.org/works?query=allen+renear&rows=0
-The maximum number rows you can ask for in one query is 1000.
The number of returned items is controlled by the rows parameter, but you can select the Nth set of rows by using the offset parameter. So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
http://api.crossref.org/works?query=allen+renear&rows=5&offset=2
-Being able to select random results is useful for both testing and sampling. You can use the sample parameter to retrieve random results. So, for example, the following select 10 random works:
http://api.crossref.org/works?sample=10
-Note that when you use the sample parameter, the rows and offset parameters are ignored.
All works published by owner prefix 10.1016 in January 2010
http://api.crossref.org/publishers/10.5555/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
-All works funded by funder_id that have a CC-BY license
- -http://api.crossref.org/publishers/10.5555/works?filter=license.uri:http://creativecommons.org/licenses/by/3.0/deed.en_US
-All works published by owner prefix 10.5555 in February 2015 that have a CC-BY license
- -http://api.crossref.org/publishers/10.5555/works?filter=license.uri:http://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2015-02,until-pub-date:2015-02
-All works funded by 10.13039/100005235 where license = CC-BY and embargo <= 365 days
http://api.crossref.org/funders/10.13039/100005235/works?filter=license.uri:http://creativecommons.org/licenses/by/3.0/deed.en_US,license.max-embargo-days:365
-All works funded by X where the archive partner listed = ‘LOCKSS’
- -Coming soon.
- -In theory, the syntax of the API can vary independently of the result representations. In practice, major version changes in either will require changes to API clients and so versioning of the API will apply to both the API syntax and the result representation.
- -The API uses a semantic versioning scheme whereby the version number is divided into three parts delimited by periods. The first number represents the “major” release number. The second represents a “minor” release number and the third represents an “internal” release number.
- -Version 1.20.31
- ^ ^ ^
- | | |
- major | |
- minor |
- internal
-Major version increments will are defined as releases that can break backwards compatibility. CrossRef will only commit to supporting the latest two major releases simultaneously and legacy major releases will be supported for no more than nine months. Exceptions to these rules may be made when major releases are required to ensure the security or stability of the system.
- -Minor version increments are defined as backwards compatible. There is no limit on the number of minor versions that can CrossRef can roll out. Note that client applications should not have dependencies on minor versions.
- -Internal version increments are simply used to keep track of development versions of the API. They should never have any effect on client applications.
- -Adding syntax options or metadata to representations will normally be backwards compatible and will thus normally only trigger minor version changes. Renaming or restructuring syntax options of metadata tends not to be backward compatible and will thus typically trigger major version changes
- -If you need to tie your implementation to a specific major version of the API, you can do so by using content-negotiation and specifying the version of the API in the ACCEPT header as follows:
application/vnd.crossref-api-message+json; version=1.0
-Minor version numbers will be ignored in ACCEPT headers as they are by definition backwards compatible.
If you omit a specific version in your ACCEPT header, the system will default to using the latest version of the API.
There will be no errors, and therefor error messages will be unnecessary. But seriously… coming soon.
- - - - - -Not implemented yet. ↩
-<free-to-read> element info. Updated warning.<free-to-read/> element documentation to reflect latest NISO work. Added information about licensing CrossRef metadata to FAQ (hint, no license required for free APIs). Added labs email address. Changed formatting.As of 2013–12–03 the <free-to-read> element has not yet been incorporated into the CrossRef deposit schema.
If you encounter problems with the API or the documentation, please report them to:
- -Funding agencies and publishers are interested in being able to measure Key Performance Indicators (KPIs) related to mandates such the February 22nd OSTP memo on Public Access to the Results of Federally Funded Research. -CrossRef is extending its FundRef Application Programming Interfaces (APIs) to enable funding agencies and publishers to query CrossRef metadata in support of generating such KPIs. Organisations such as CHORUS and SHARE can make use of these APIs in order to create KPI Dashboards measuring, amongst other things:
- -The CrossRef extended APIs, of course, will only work if publishers supply the appropriate metadata. This document outlines the metadata that publishers will need to provide in order to support such KPI reporting.
- -Although this document is not an RFC, it will follow the conventions of rfc2119 in the use of the following terms:
- -In order to support basic agency and publisher KPIs:
- -In order to enhance the utility of CrossRef metadata to agencies and in order to enable more sophisticated agency/publisher KPIs:
- -<metadata_distribution_opt> and <reference_distribution_opt> elements.CrossRef supports the recording of funding information for a publication via its FundRef program. FundRef defines an open, standard registry of funder names and funder identifiers that can be used in order to increase the accuracy of the funding information recorded. Although FundRef supports recording award_numbers along with funder identifiers, FundRef does not define standards for recording award numbers as practice varies greatly across funders.
- -To support funder KPIs, members must deposits funder metadata using the specifications defined for the FundRef program. Specifically, when depositing metadata you:
- -See CrossRef’s Help pages for Technical details on depositing FundRef metadata.
- -One of the main drivers for the FunRef KPI API is that many funders are required to report on the public availability of the results and publications arising from funder-financed research. Funders are therefor interested in understanding how publications related to funded research are licensed.
- -To deposit license information, publishers must use the <license_ref> element. The value of the <license_ref> element must be a stable HTTP URI which points to a human-readable document that either includes (or guides the reader to) any copyright and/or licensing information related to the CrossRef DOI of the content. The URI must point either to a location on the publisher’s site or to the stable location of any well-known licenses such as those of the Creative Commons.
Note that it is entirely acceptable to record a <license_ref> URI as a “placeholder.” If you are still working out specific licensing terms, the URI you record should point to a blank page or even a simple re-assertion of the document’s copyright. There is a big difference between recording at least some <license_ref> URI and recording no <license_ref> URI at all. The former indicates an intent to eventually clarify licensing information, whereas the latter indicates that the licensing information is likely to remain ambiguous.
Use of the <license_ref> element is best explained through examples.
The <license_ref> for content licensed under the popular CC-BY license, would look like this:
<license_ref>http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-Where as the Journal of Psychoceramics might record that their content is licensed under a proprietary license like this:
- -<license_ref>http://www.psychoceramics.org/license_v1.html</license_ref>
-You can deposit multiple <license_ref> elements- so the following would indicate that a document was available under a dual license (e.g. one for commercial applications and one for non-commercial applications).
<license_ref>http://www.psychoceramics.org/non_commercial_license_v1.html</license_ref>
-<license_ref>http://www.psychoceramics.org/commercial_license_v1.html</license_ref>
-Publishers may want to record that a document is under embargo. In other words, that it is available under access control and a proprietary license for a set period of time, after which it is available under an open license. Publishers wishing to record embargoes should use the optional start_date attribute on the <license_ref> element.
For example, the following records that the content is under a proprietary license from its date of publication on February 3, 2014 and that it is under a CC-BY license a year later on February 3, 2015:
- -<license_ref start_date="2014-02-03">http://www.psychoceramics.org/license_v1.html</license_ref>
-<license_ref start_date="2015-02-03">http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-Note that the value of the start_date element must be recorded using the format YYYY-MM-DD
-The start_date attribute can be combined with multiple <license_ref> elements to indicate that a document is under a proprietary license during an embargo, but that it is then under a dual (commercial/non-commercial) license a year later)
<license_ref start_date="2014-02-03">http://www.psychoceramics.org/license_v1.html</license_ref>
-
-<license_ref start_date="2015-02-03">http://www.psychoceramics.org/non_commercial_license_v1.html</license_ref>
-
-<license_ref start_date="2015-02-03">http://www.psychoceramics.org/commercial_license_v1.html</license_ref>
-Note that there is no corresponding end_date attribute for the <license_ref> element. This is because including end dates could introduce ambiguities. For example:
You might ask why one should record a license that starts in the future? Wouldn’t it be better to just update the <license_ref> element at the time the license changes? By recording that another license takes effect in the future, you are informing the consumer of the metadata that the current restricted license is only for the embargo period. In short, you are recording the intent to change the license when the embargo is done. Furthermore, providing additional metadata for a current publication at some future date is an additional chore for the publisher that might well be overlooked.
In the above examples, the <license_ref> element is unqualified and should therefor be considered to apply to the content pointed to by any <resource> URIs included in the CrossRef metadata. The CrossRef metadata schema supports recording different license for different versions of the resource and this will be discussed below. However, first let’s look at at the role the <resource> element plays in providing funding agency KPIs.
Funders are not just interested in reporting on the licensing terms of publications resulting from funder-financed research. They are also interested in making sure that the full text content of the BAV is made available for reading, automated processing and archiving.
- -To this end, publishers need to be able to record links to the full text of the content to which a DOI refers. Additionally, publishers will want to offer different versions (e.g. AM or VOR) and different representations (e.g. PDF for viewing, XML for TDM, etc.) of the content tailored for specific applications.
- -The <resource> element in CrossRef metadata is most often used to record an HTTP URI pointing at the publisher’s landing page for the publication identified by the CrossRef DOI in question. However, the CrossRef schema has long supported the recording of multiple <resource> elements in order to enable, for example:
CrossRef has extended the ability to record multiple <resource> elements in order to allow the recording of URIs which point to the full text of content identified by the CrossRef DOI. The publisher can record multiple representations of the full text (e.g. PDF, XML, plain text) using the new mime_type attribute and then, through their access control systems, control who is able to reach which representation and under which conditions.
Note that, by recording a <resource> that points to the full text, you are not necessarily guaranteeing that the URI will be accessible
Note also that the publisher could theoretically choose only to deposit <resource> elements for full text representations once an embargo has ended. However, this approach may prove fraught, as any mistakes or delays in the redeposit process might lead the funding agency to believe that the publisher has not made the relevant content accessible at the end of the embargo period.
Further detail on using the <resource> element for recording links to full text can be found on the Prospect support site and in the CrossRef deposit schema documentation for the <collection> and <resource> elements.
Some publishers may want to record different licenses for different versions of the <resource> element recorded in CrossRef metadata. For example, one <resource> element may point to a URI intended for subscribed readers, while another <resource> element may point to a version of the document intended for Text and Data Mining (TDM) applications. Similarly, a publisher may choose to apply one license to the “Author Accepted Manuscript” (AM) and another to the “Version of Record” (VOR).
To accommodate these scenarios, the <license_ref> element supports an applies_to element. Similarly, the <resource> element has been extended to support a content_version attribute. Publishers can use these element/attribute combinations to apply specific licenses to specific versions of the resource. For example, to indicate the “VOR” version of a document is licensed under a proprietary license, but that the “AM” version of the same document is licensed under an open license, the <license_ref> and <resource> elements could be combined like this:
<license_ref applies_to="vor">http://www.psychoceramics.org/license_v1.html</license_ref>
-
-<!-- … -->
-
-<license_ref applies_to="am">http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-
-<!--- other CrossRef metadata -->
-
-<resource content_version="vor">http://www.psychoceramics.org/fulltext/vor/10.5555/12345678</resource>
-
-<!-- … -->
-
-<resource content_version="am">http://www.psychoceramics.org/fulltext/am/10.5555/12345678</resource>
-The <license_ref> and <resource> elements along with their respective start_date, applies_to, and content_type attributes can all be combined to support more complex assertions. So, for example the following example says that a document is only available under a proprietary license for readers during an embargo period, but is then available to the public for reading under a more open license and for non-commercial TDM applications under a specific TDM license:
<license_ref start_date="2014-02-03" applies_to="vor">http://www.psychoceramics.org/license_v1.html</license_ref>
-
-<!-- … -->
-
-<license_ref start_date="2015-02-03" applies_to="am">http://www.psychoceramics.org/open_license.html</license_ref>
-
-<!-- … -->
-
-<license_ref start_date="2015-02-03" applies_to="tdm">http://www.psychoceramics.org/nc_tdm_license.html</license_ref>
-
-<!--- other CrossRef Metadata -->
-
-<resource content_version="vor">http://www.psychoceramics.org/fulltext/vor/10.5555/12345678</resource>
-
-<!-- … -->
-
-<resource content_version="am">http://www.psychoceramics.org/fulltext/am/10.5555/12345678</resource>
-
-<resource content_version="tdm">http://www.psychoceramics.org/fulltext/tdm/10.5555/12345678.xml</resource>
-Detailed information on recording licensing information in CrossRef metadata can be found in the CrossRef schema documentation for the <license_ref> element.
The license information recorded in the <licence_ref> element can tell you what you are allowed to do with the resources the licenses point to, but they do not say anything about whether or not there is a monetary charge involved.
-In order to allow a publisher to record whether access to the content requires payment, CrossRef supports a new <free-to-read/> element. The <free-to-read/> element is an empty element. It can include two attributes, a start_date and an end_date. The <free-to-read/> elements works as follows:
start_date attribute, then the element should be interpreted to mean that the content pointed to by the DOI resource will be made gratis from start_date on.end_date attribute, then the element should be interpreted to mean that the content pointed to by the DOI resource will be made gratis from the publication date to and including the end_date.start_date or end_date attributes, then the element should be interpreted to mean that the content pointed to by the DOI resource is available “gratis” from the date of publication on.When the <free-to-read> element is combined with the <license_ref> element, the publisher can record sophisticated information about the availability and reusability of content. For example:
restrictive licenses and possibly a payment
- -<license_ref>http://tinypublisher.org/licenses/proprietary.html</license_ref>
-restrictive licenses and no payment (e.g free copy of an article from a subscription journal)
- -<free-to-read/>
-<!-- … -->
-<license_ref>http://tinypublisher.org/licenses/proprietary.html</license_ref>
-have unrestrictive licenses and a possibly a payment (e.g. a CC-BY licensed novel for sale on Amazon)
- -<license_ref>http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-have unrestricted licenses and NO payment
- -<free-to-read/>
-<!-- … -->
-<license_ref>http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-The more metadata that publishers record for publications arising from agency funded research, the more useful that metadata will be to said agencies and the more value they will see from publishers. Where as the above sections details metadata elements that agencies will expect in order to be able to compile basic KPIs and offer portal services, additional metadata will allow agencies to create even more sophisticated KPIs and services. As such, publishers should seriously consider depositing the following additional metadata elements in their CrossRef deposits.
- -Metadata deposited to CrossRef is made available freely via numerous CrossRef query APIs. However all deposited metadata is subject to opt-outs in the case of bulk distribution APIs and data dumps. In order to make sure that bibliographic metadata for publications arising from agency funding is maximally available, publishers should consider setting the value of the <metadata_distribution_opts> element for DOIs to any. Further details can be found in CrossRef’s schema documentation for the <metadata_distribution_opts> element.
References made in publications arising from agency funding can provide agencies with an overview of what literature is considered important in the fields that they fund. Many publishers deposit references to CrossRef as part of their participation CrossRef’s CitedBy service. However, participation in CitedBy does not automatically make references available via CrossRef’s standard APIs. In order for publishers to distribute references along with standard bibliographic metadata, publishers need to set the <reference_distribution_opt> element to any for each DOI deposit where they want to make references openly available. By setting this element, references for the DOI will be distributed without restriction through all of CrossRefs APIs and bulk metadata dumps. Further details can be found in CrossRef’s schema documentation for the <reference_distribution_opt> element.
CrossMark provides a standard mechanism for alerting researchers to updates to published documents- including corrections, errata, corrigenda retractions and withdrawals. Use of the CrossMark service sends a signal to researchers and agencies that publishers are committed to maintaining the integrity of the scholarly record.
- -Additionally, CrossMark also provides a standard, cross-publisher, user interface that researchers can use to view FundRef information and licensing information. This user interface works both from publisher landing pages and from published PDFs. More information can be found on the CrossMark support site
- -Many funding agencies are interested in building custom portals that highlight agency-funded research. In order to provide users of these portals with the best experience, agencies will want, where possible, to display abstracts of publications along with their standard bibliographic metadata.
- -CrossRef supports the deposit of abstracts conforming to the JATS abstract element. Further details can be found in the CrossRef Schema Documentation of the <abstract> element.
ORCIDs are unique identifiers for researchers. CrossRef supports the deposit of ORCIDs for authors. The presence of ORCIDs in CrossRef metadata will, in turn, allow agencies to tie agency funded research publications directly to researchers. Widespread use of ORCIDs in CrossRef deposits could even let agencies start to develop publication KPIs for researchers that they fund. Further details on CrossRef’s ORCID support can be found in the CrossRef Schema Documentation of the <ORCID> element
Q: What license applies to the metadata retrieved by the CrossRef APIs to support key performance indicators (KPIs) for funding agencies?
-
-A: CrossRef asserts no claims of ownership to individual items of bibliographic metadata and associated Digital Object Identifiers (DOIs) acquired through the use of the CrossRef Free Services. Individual items of bibliographic metadata and associated DOIs may be cached and incorporated into the user’s content and systems. More information can be found on our web site.
Q: What does it mean if a <license_ref> element has no start_date attribute?
-
-A: This should be interpreted to mean that the <license_ref> applies from the earliest publication date.
Q: What does is mean if there is no applies_to attribute for the <license_ref> element?
-
-A: This should be interpreted to mean that the license_ref applies to all the <resource> elements in the record.
Q: What does it mean if the <resource> element doesn’t have a content_version attribute?
-
-A: This should be interpreted to mean that any <resource> elements point to the version of record (‘vor’)
Q: What does it mean if there is no correspondence between existing <license_ref> applies_to attributes and existing <resource> content_version attributes?
-
-A: This probably means the publisher made a mistake depositing the metadata.
Full deposits use the standard deposit schema.
- - - -Partial deposits use the resource deposit schema.
- -Partial deposits update only part of a DOI’s metadata. In the CrossRef help system -they are referred to as resource deposits, but it is not just resources that can -be provided as a partial deposit. Licenses, funding information and CrossMarks can also -be provided as partial deposits.
- -Many partial deposits can be provided in a single batch deposit. The <body> element can
-contain any number of partial deposits of any type, some of which may be partial deposits for
-the same DOI. For example, two partial deposits could be provided for the same DOI,
-one updating funding information, the other updating license information.