Get Retraction Watch metadata from Crossref’s API

Author
Affiliation

Luis M. Montilla

Crossref

In this tutorial you will:
  • Learn how to identify the update metadata in records pulled from Crossref REST API.
  • Understand what filters to use to retrieve records based on update metadata

What you need to know

As you might know, part of the scholarly metadata that you can find in Crossref’s REST API includes updates made to specific works. More recently we also annouced:

Retractions and corrections from Retraction Watch are now available in Crossref’s REST API. Back in September 2023, we announced the acquisition of the Retraction Watch database with an ongoing shared service. Since then, they have sent us regular updates, which are publicly available as a csv file. Our aim has always been to better integrate these retractions with our existing metadata, and today we’ve met that goal.1

In this tutorial we’ll show how to understand and retrieve this metadata. We need to understand how this information will be expressed in the REST API, so let’s take a look at both ends of the relationship: a record that has an update and a record that represents an update to another one:

Identify the update metadata

Let’s examine a record that contains update metadata: ´https://api.crossref.org/v1/works/10.1177/1758835920922055´

In the following box you will see this record retrieved from the works endpoint in JSON format, as it’s normally returned from the REST API. You can collapse any key by clicking the litle triangle to the left of the key name. Can you find the key called updated-by?. Just click the magnifying glass icon on top and type or paste updated-by.

You should see a lot of interesting information there, including the DOI that identify the retraction. Let’s take a look at the complementary record; use the same tools to now find the update-to key:

If you expand the keys type and source you will understand why there are two entries in this record. In this case, the updates are coming from two sources: from Retraction Watch and also from the publisher.

Retrieve many records with updates

You can use the works endpoint with the filter filter=update-type:retraction in your regular API call, e.g. https://api.crossref.org/v1/works?filter=update-type:retraction. Let’s use this in combination with rows to get a quick idea of the number of records with retractions:

Tip

Don’t forget to add the mailto parameter with your contact email address to direft your request to our Polite pool.

Code 
jsonedit(jsonlite::fromJSON("https://api.crossref.org/v1/works?filter=update-type:retraction&rows=0&mailto=learning@crossref.org"))

Other methods

You can also go to our gitlab repository and download a .CSV file that you can open in your text or spreadsheet editor of choice: Retraction Watch data.

In conclusion
  • You can get Retraction Watch metadata from the Crossref REST API.
  • Find the updated-by and/or update-to keys.
  • Use the filter filter=update-type:retraction to get multiple records.

Other resources