The Crossref Curriculum

Retrieving Cited-by matches

Cited-by matches may be retrieved through HTTPS queries, OAI-PMH queries, or XML queries. Note that Cited-by matches for posted content are excluded by default.

HTTPS queries (for DOIs or prefixes)

We support HTTPS querying for Cited-by matches. Results may be retrieved by individual DOI or for an entire prefix, and are returned as XML with some basic metadata included.

DOI query (results by DOI or prefix)

This format retrieves all Cited-by matches for a single DOI (or prefix) within a specified date range:

https://0-doi-crossref-org.libus.csd.mu.edu/servlet/getForwardLinks?usr=username&pwd=password&doi=doi&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD

You may also retrieve Cited-by matches established on a single day for a single DOI or prefix:

https://0-doi-crossref-org.libus.csd.mu.edu/servlet/getForwardLinks?usr=username&pwd=password&doi=prefix&date=YYYY-MM-DD

Date range (startDate and endDate, or YYYY-MM-DD) and doi parameters are required. Results for an entire prefix may be retrieved by supplying the prefix as the doi value. Depending on the volume of matches, this query might time out, so a short date range is recommended.

Results of HTTPS queries are returned using Crossref’s query output schema. The total citations is the number of items in the list and the number of citations of each cited work is included for per item using the tag fl_count.

OAI-PMH request (results by prefix or title)

This format retrieves Cited-by matches established within a date range for a prefix or for a given title. Supply a prefix only (no pubID) to retrieve all results for a prefix. Only the prefix owner may retrieve matches. A date range is required.

https://0-oai-crossref-org.libus.csd.mu.edu/OAIHandler?verb=ListRecords&usr=username&pwd=password&set=J:prefix:pubID&from=YYYY-MM-DD&until=YYYY-MM-DD&metadataPrefix=cr_citedby

where:

  • username and password = Crossref admin tool username and password for the prefix/title being retrieved
  • content type = J for journal; B for books, conference proceedings, datasets, reports, standards, or dissertations; and S for series
  • Prefix = the owning prefix of the title being retrieved
  • pubID = the publication identification number assigned by the system.

OAI-PMH results

OAI-PMH requests only return a list of citing DOIs. Metadata is not included, but can be retrieved with a DOI-to-metadata query.

<OAI-PMH xsi:schemaLocation="http://www.openarchives.org/OAI/2.0/ http://www.openarchives.org/OAI/2.0/OAI-PMH.xsd" xmlns="http://www.openarchives.org/OAI/2.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<responseDate>2011-12-13T09:51:59</responseDate>
<request verb="ListRecords" set="J:10.1007:3234">http://0-oai.crossref.org.libus.csd.mu.edu/OAIHandler</request>
<ListRecords>
 <record>
  <header>
	<identifier>info:doi/10.1007/BF00705816</identifier>
	<datestamp>2009-04-21</datestamp>
	<setSpec>J:10.1007:3234</setSpec>
  </header>
  <metadata>
	<citations>
 	<citation xmlns="http://0-www.crossref.org.libus.csd.mu.edu/schema/crossref_citations_1.0.0">
 	<doi>10.1007/BF00705816</doi>
  	<citations-cited-by>
   	<doi>10.1007/BF01133383</doi>
   	<doi>10.1016/S0167-577X(97)00196-1</doi>
   	<doi>10.1016/j.desal.2006.03.578</doi>
   	<doi>10.1007/s11771-008-0060-5</doi>
   	<doi>10.1016/S0025-5408(99)00105-1</doi>
   	<doi>10.1016/j.micromeso.2005.05.016</doi>
   	<doi>10.1016/S0924-2031(99)00058-2</doi>
   	<doi>10.1002/jrs.1250260840</doi>
   	<doi>10.1007/BF02903455</doi>
 	</citations-cited-by>
	</citation>
   </citations>
  </metadata>
</record>

Some OAI-PMH requests are too big to be retrieved in a single transaction. If a given response contains a resumption token the user must make an additional request to retrieve the rest of the data. Learn more about resumption tokens, and OAI-PMH requests.

XML queries (by DOI)

You may submit a simple XML query to retrieve Cited-by matches. The query contains only the DOI of the cited article stored in the fl_query element. For best results, each XML file should contain a single DOI.

Setting the alert attribute to “true” instructs the system to remember this query and to send new Cited-by link results to the specified email address when they occur.

<?xml version = "1.0" encoding="UTF-8"?>
<query_batch version="2.0" xmlns = "http://0-www.crossref.org.libus.csd.mu.edu/qschema/2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://0-www.crossref.org.libus.csd.mu.edu/qschema/2.0 http://0-www.crossref.org.libus.csd.mu.edu/qschema/crossref_query_input2.0.xsd">
<head>
	<email_address>your@email.com</email_address>
 	<doi_batch_id>fl_001</doi_batch_id>
</head>
<body>
	<fl_query alert="true">
  	<doi>10.1053/sonc.2002.35642</doi>
	</fl_query>
</body>
</query_batch>

To get alert emails for future Cited-by matches, the XML query has to include alert="true” in the <fl_query> tag as above.

Cited-by linking XML queries can be submitted just like any other XML query.

XML and HTTPS query results

Both HTTPS and XML queries will return results as XML, formatted using our query output schema section. Only basic bibliographic metadata is returned. If you want to retrieve complete or non-bibliographic metadata, you can perform OAI-PMH queries to retrieve DOI matches, then do DOI-to-metadata queries to retrieve a full metadata record for each DOI.

Result with matches

<?xml version="1.0" encoding="UTF-8"?>
<crossref_result version="2.0" xmlns="http://0-www.crossref.org.libus.csd.mu.edu/qrschema/2.0.xsd">
<query_result>
<head>
   <email_address>support@crossref.org</email_address>
   <doi_batch_id>fl_001</doi_batch_id>
</head>
<body>
 <forward_link doi="10.1053/sonc.2002.35642">
   <journal_cite>
 	<issn type="electronic">15321827</issn>
  	<issn type="print">00070920</issn>
   	<journal_title>British Journal of Cancer</journal_title>
     	<article_title>Introduction</article_title>
      	<contributors>
          	<contributor first-author="true">
           	<given_name>U</given_name>                           	 
           	<surname>Gatzemeier</surname>
          	</contributor>
       	</contributors>
       	<volume>89</volume>
       	<first_page>S1</first_page>
       	<year>2003</year>
       	<publication_type>full_text</publication_type>
       	<doi type="journal_article">10.1038/sj.bjc.6601475</doi>
	</journal_cite>
  </forward_link>
  <forward_link doi="10.1053/sonc.2002.35642">
   	<journal_cite>
       	<issn type="print">10870156</issn>
        	<journal_title>Nature Biotechnology</journal_title>
        	<article_title>Monoclonal antibody therapy of cancer</article_title>
        	<contributors>
            	<contributor first-author="true">
                	<given_name>Gregory P</given_name>
                	<surname>Adams</surname>
            	</contributor>
            	<contributor first-author="false">
              	<given_name>Louis M</given_name>
              	<surname>Weiner</surname>
            	</contributor>
        	</contributors>
        	<volume>23</volume>
        	<issue>9</issue>
        	<first_page>1147</first_page>
        	<year>2005</year>
        	<publication_type>full_text</publication_type>
        	<doi type="journal_article">10.1038/nbt1137</doi>
    	</journal_cite>
   </forward_link>
   <forward_link doi="10.1053/sonc.2002.35642">
  	<journal_cite>
      	<issn type="print">08853177</issn>

Response with no matches

Responses with no Cited-by matches will return an empty <body/> tag

<?xml version="1.0" encoding="UTF-8"?>
  <crossref_result version="2.0" xsi:schemaLocation="https://0-www-crossref-org.libus.csd.mu.edu/qrschema/2.0 https://0-www-crossref-org.libus.csd.mu.edu/qrschema/crossref_query_output2.0.xsd" xmlns="https://0-www-crossref-org.libus.csd.mu.edu/qrschema/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <query_result>
      <head>
        <email_address>none</email_address>
        <doi_batch_id>none</doi_batch_id>
      </head>
      <body/>
     </query_result>
  </crossref_result>

Example alert email

Note that alerts are not emailed immediately when a Cited-by match is made, there is sometimes a delay of several weeks.

From: CrossRef Query System admin@crossref.org
Subject: Aggregated notifications from Crossref [forward-link]
Date: July 27, 2017 at 2:01:16 AM EDT
To: “user@example.orguser@example.org

<?xml version="1.0" encoding="UTF-8"?><crossref_result xmlns="https://0-www-crossref-org.libus.csd.mu.edu/qrschema/2.0" version="2.0"><query_result><head><email_address>admin@crossref.org</email_address><doi_batch_id>aggregated</doi_batch_id></head><body><forward_link doi="10.xxx/xxxx">
 <journal_cite fl_count="0">
   <issn type="print">1367-9430</issn>
   <journal_title>Animal Conservation</journal_title>
   <journal_abbreviation>Anim Conserv</journal_abbreviation>
   <article_title>How to make (in)effective conservation projects: look at the internal context!</article_title>
   <contributors>
     <contributor first-author="true" sequence="first" contributor_role="author">
       <given_name>C.</given_name>
       <surname>Battisti</surname>
     </contributor>
   </contributors>
   <volume>20</volume>
   <issue>4</issue>
   <first_page>305</first_page>
   <year>2017</year>
   <publication_type>full_text</publication_type>
   <doi type="journal_article">10.xxx/xxx.xxxx</doi>
 </journal_cite>
</forward_link></body></query_result></crossref_result>

Cited-by matches and posted content

Members querying for Cited-by matches may choose to include posted content (such as preprints) matches in their results. By default, posted content is not included. To retrieve matches including posted content:

HTTPS queries: add the “include_postedcontent=true” parameter to your query, for example:

https://0-doi-crossref-org.libus.csd.mu.edu/servlet/getForwardLinks?usr=xxx&pwd=xxx&doi=10.5555/12345678&include_postedcontent=true

XML queries: add the “include_postedcontent="true” attribute to your fl_query element, for example:

<?xml version = "1.0" encoding="UTF-8"?>
<query_batch version="2.0" xmlns = "https://0-www-crossref-org.libus.csd.mu.edu/qschema/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<head><doi_batch_id>eXtyles Request AMP.dodge0724.doc__76</doi_batch_id></head>
<body>
<fl_query **include_postedcontent="true"**
><doi>10.5555/12345678</doi></fl_query>
</body>
</query_batch>

Manual retrieval methods

Example of an article with Cited-bys https://0-doi-org.libus.csd.mu.edu/10.1088/1367-2630/1/1/006


Example queries

https://0-doi-crossref-org.libus.csd.mu.edu/servlet/getForwardLinks?usr=ufg&pwd=ufg1957&doi=10.5216/cab.v13i4.15617
https://0-doi-crossref-org.libus.csd.mu.edu/servlet/getForwardLinks?usr=ufg&pwd=ufg1957&doi=10.5216&startDate=2018-11-01&endDate=2018-12-01

Template

Can get just the number and no details from the REST API http://0-api.crossref.org.libus.csd.mu.edu/works/10.1088/1367-2630/1/1/006 (see is-referenced-by-count)

Cited-by count in XML API https://0-doi-crossref-org.libus.csd.mu.edu/search/doi?pid=support@crossref.org&amp;format=unixsd&amp;doi=10.5216/cab.v13i4.15617

Cited-by case study

Goal 1: To query Crossref APIs to understand which of my DOIs have received citations during a specified timeframe.

Result for:

http://0-oai.crossref.org.libus.csd.mu.edu/OAIHandler?verb=ListRecords&usr=[username]&pwd=[password]&set=J:10.21061:300318&from=2019-07-01&until=2019-12-31&metadataPrefix=cr_citedby

The OAIHandler/ListRecords request has an interesting implementation regarding dates. The date range query is matching any cited-by relationships that have been updated within the date range in which the target DOI (the one being cited) is in the setspec.

So if you, as a publisher, are querying the cited-by relations of your DOI, it doesn’t matter what the update date of your DOI is. If any DOI that cites your DOI was updated during the timeframe, your DOI and all DOIs citing your DOI will be returned, regardless of any of the other dates, because the cited-by relations for your DOI have changed during that timeframe.

Compare this with:

https://0-doi-crossref-org.libus.csd.mu.edu/servlet/getForwardLinks?usr=[username]&pwd=[password]&doi=10.21061/jte.v26i2.a.2&startDate=2019-07-01&endDate=2019-12-31

This is essentially the same as the previous example, except that this only shows 10.21061/jte.v26i2.a.2 and the ONE citer (10.1111/ssm.12376) that changed during the date range. It omits the other DOIs for that journal, since only the one DOI was queried, but the data for the given DOI is the same in both results.

And another comparison:

https://0-doi-crossref-org.libus.csd.mu.edu/servlet/getForwardLinks?usr=[username]&pwd=[password]&doi=10.21061/jte.v26i2.a.2

This call only queries one DOI and omits a date range, so this shows all 13 relationships just as the first OAIHandler request does, though the format is different.

Goal 2: To query Crossref APIs to get a list of all of my DOIs that have been cited for my prefix as a whole for a specified timeframe.

Result for the last year:

https://0-doi-crossref-org.libus.csd.mu.edu/servlet/getForwardLinks?usr=[username]&pwd=[password]&doi=10.21061&startDate=2019-01-01&endDate=2019-12-31

Result for a more specific timeframe:

https://0-doi-crossref-org.libus.csd.mu.edu/servlet/getForwardLinks?usr=[username]&pwd=[password]&doi=10.21061&startDate=2020-01-01&endDate=2020-03-22

Page owner: Laura J. Wilkinson   |   Last updated 2020-April-08