Documentation

Metadata Retrieval

The collective power of our members’ metadata is available to use through a variety of tools and APIs—allowing anyone to search and reuse the metadata in sophisticated ways.

Members register content with us to let the world know it exists. They send us information called metadata which we collect and store in a standard way. Metadata does not include the full-text of the content itself, just information about the content. The metadata includes a Digital Object Identifier (DOI) in each record, which links to the content even if it moves to a new website. We make this metadata openly available via our APIs and public data files, which means people and machines can incorporate it into their research tools and services. While we collect and distribute metadata, we do not change members’ metadata. Learn more about the metadata each member is depositing with us using our Participation Reports.

Manuscript tracking services, search services, bibliographic management software, library systems, author profiling tools, specialist subject databases, scholarly sharing networks - all of these (and more) incorporate scholarly metadata into their software and services. They use our free APIs to help them get the most complete, up-to-date set of metadata from all of our publisher members. And of course, members themselves are able to use our free APIs and public data files too.

Metadata users and uses: metadata from Crossref APIs is used for a variety of purposes by many tools and services

Watch the introductory animation in your language:français;español;português do Brasil;简体中文;日本語;한국어;العربية;bahasa Indonesia; or English below.

 

How metadata retrieval works

To retrieve metadata from Crossref, you do not need to be a member. We have various options for retrieving metadata - some are more suitable for human use, and some for machine use.

There are interfaces for people (to look up small numbers of DOIs): Metadata Search, and Simple Text Query.

There are APIs for machines (to look up metadata records or DOIs in volume), including: REST API, XML API, OAI-PMH, and OpenURL; and our paid Metadata Plus service.

There are public data files published annually containing the entirety of our metadata corpus. The first public data file was published in 2020, and the most recent public data file is available at Academic Torrents or directly from AWS for a small fee.

Take a look at a list of some of the organizations who rely on our REST API.

Here is a comparison of the metadata retrieval options. Please note that all interfaces include Crossref test prefixes: 10.13003, 10.13039, 10.18810, 10.32013, 10.50505, 10.5555, 10.88888.

Feature / optionMetadata SearchSimple Text QueryREST APIXML APIOAI-PMHOpenURLPublic data filesMetadata Plus (OAI-PMH + REST API)
Interface for people or machines?PeoplePeoplePeople (low volume and occasional use) and machinesMachinesMachinesMachinesMachinesMachines
Output formatText, JSONTextJSONXMLXMLXMLjson.tar.gzJSON, XML
Suitable for citation matching?Yes (low volume)YesYesYesNoNoYes, locallyYes
Supports volume downloads?NoNoYesNoYesNoYes, exclusivelyYes
Suitable for usage typeFrequent and occasionalFrequent and occasionalFrequent and occasionalFrequentFrequentFrequentOccasionalFrequent and occasional
Free or cost?FreeFreeFree and cost optionsFree and cost optionsCost for full service, more options availableFreeFreeCost
Includes all available metadata?In JSON onlyDOIs onlyYesYesYesBibliographic onlyYesYes
DocumentationMetadata SearchSimple Text QueryREST APIXML APIOAI-PMHOpenURLTips for working with Crossref public data files and Plus snapshotsMetadata Plus (OAI-PMH + REST API)

If you’d like to share a case study for how you use Crossref metadata, and be featured on our blog, please contact us.

Using content negotiation

The APIs listed here provide metadata in a variety of representations (also known as output formats). If you want to access our metadata in a particular representation (for example, RDF, BibTex, XML, CSL), you can use content negotiation to retrieve the metadata for a DOI in the representation you want. Content negotiation is supported by a number of DOI registration agencies including Crossref, DataCite, and mEDRA.

Obligations and fees for metadata retrieval

It is important that members understand that metadata is used by other software and services in the Crossref community. We encourage members to submit as much metadata as possible so that our APIs can include and deliver rich contextual information about their content.

If you’re using the public REST API, it is optional but encouraged to include your email address in header requests as this puts your query into the “polite” pool which has priority processing. Learn more about our REST API etiquette.

All of our metadata is freely available, but there is a fee for our premium Metadata Plus service.

Crossref generally provides metadata without restriction; however, some abstracts contained in the metadata may be subject to copyright by publishers or authors.

How to participate - interfaces for people

Crossref provides a number of user interfaces to access Crossref metadata. Some are general-purpose, and others are more specialized.

Service nameDescription
Metadata SearchMetadata Search is our primary user interface for searching and filtering of our metadata. It can be used to look up the DOI for a reference or a partial reference or a set of references, to look up metadata for a content item, submit a query on an author’s name, or find retractions registered with us. It can also be used to search and filter a number of elements, including funding data, ISSN, ORCID iDs, and more.
Simple Text QuerySimple Text Query is a tool designed to allow anyone to look up DOIs for multiple references. As such it’s particularly useful for members who want to link their references. Members can even use this tool to add linked references to their metadata.

How to participate - APIs for machines

We have a number of APIs for accessing metadata. There is one general-purpose API and several specialized ones. The specialized APIs are designed for our members so that they can manage their metadata or they are APIs based on standards that are popular in the community.

API nameDescription
REST APIThe REST API outputs in JSON and enables sophisticated, flexible machine and programmatic access to search and filter our metadata. It can be used, for example, to look up the metadata for a content item or submit a query on an author’s name or find retractions registered with us. It also allows users to search and filter on a number of elements, including a funder, or all content items with ORCID iDs. The REST API is open to all and it is included in the Metadata Plus service.
OpenURLThis API lets you look up a Crossref DOI for a reference, using a standard that is popular in the library community, and particularly with link resolver services.
OAI-PMHThis API outputs in XML and uses a standard popular in the library community to harvest metadata. The OAI-PMH API is optimized to return a list of results matching the query parameters (such as publication year). The OAI-PMH API is included in the Metadata Plus service.
XML APIThe XML API supports XML-formatted querying. The XML API is optimized to return the best fit DOI based on the metadata supplied in the query.
Public data filesWhile the public data files are not an API, they are freely available bulk downloads of the full Crossref metadata corpus, published annually. It can be downloaded via Academic Torrents, or directly from AWS for a small fee.
Metadata retrieval infographic

Download the metadata retrieval factsheet, and explore factsheets for other Crossref services and in different languages.

Looking up metadata and identifiers

We support a range of tools and APIs to help you get metadata (and identifiers) out of our system. Some query interfaces will return only one match, and only if fairly strict requirements are met. These interfaces may be used to populate citations with persistent identifiers. Other interfaces will return a range of results and may be used to retrieve a variety of metadata records or match metadata when metadata, DOIs, or other identifiers (such as ORCID iD, ISSN, ISBN, funder identifier) are provided.

User interfaces

  • Metadata Search - any results containing the entered search terms will be returned. Search by full citation, title (or fragments of a title), authors, ISSN, ORCID, DOI (to retrieve metadata) and more.
  • Simple Text Query - cut-and-paste your reference list into the form and retrieve exact DOI matches.

APIs

  • REST API - a RESTful API that supports a wide range of facets and filters. By default, results are returned in JSON, and returning results in XML is an option. This API is currently publicly available (no account or token required), but there is a paid Metadata Plus service available on a token for those who require guaranteed service levels
  • XML API - the XML API will return a DOI that best fits the metadata supplied in the query. This API is suitable for automated population of citations with DOIs as the results are accurate and do not need evaluation. This API is available to members, or by supplying an email address.
  • OpenURL - used mostly by libraries but also available to members, or by providing an email address. Learn more about OpenURL access.
  • OAI-PMH - as well as a free public list option, we provide a subscription-only OAI-PMH interface that may be used to retrieve sets of metadata records (subscribers only)
  • GetResolvedRefs - retrieve DOIs matched with deposited references (members only)
  • Deposit harvester - retrieve DOIs and metadata for a given member (members only).

Page owner: Patrick Polischuk   |   Last updated 2020-April-08