XML API
The XML API returns lists of metadata records in XML format. Requests can be made using a DOI or querying in XML format. Its main uses include:
- Retrieving metadata for a DOI in XML format.
- Finding the DOI for an item based on bibliographic metadata.
- For Crossref members, retrieve bibliographic metadata for content items that cite your own. These are known as forward links.
The XML API is the closest to member-deposited metadata, so is also useful for members to verify that deposited metadata is publicly available.
On this page:
Quick start
This section contains examples to demonstrate how to make requests of the XML API. See below for descriptions of the parameters available for each endpoint. Replace the example email addresses with your own before using these examples. For readability, these requests have not been URL encoded.
- Retrieve metadata for a single content item based on its DOI:
https://doi.crossref.org/search/doi?pid=email@address.com&doi=10.1577/H02-043&format=unixsd
- Search for a content item using an unstructured citation (see additional query examples):
https://doi.crossref.org/servlet/query?usr=email@address.com&format=unixref&qdata=<?xml version = "1.0" encoding="UTF-8"?>
<query_batch xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0"
xmlns="http://www.crossref.org/qschema/2.0" xsi:schemaLocation="http://www.crossref.org/qschema/2.0 http://www.crossref.org/qschema/crossref_query_input2.0.xsd">
<head>
<email_address>your@email.org</email_address>
<doi_batch_id>my_batch_label</doi_batch_id>
</head>
<body>
<query key="q1" enable-multiple-hits="true">
<unstructured_citation>Hungate, B. A., & Hampton, H. M. (2012). Ecosystem services: Valuing ecosystems for climate. Nature Climate Change, 2(3), 151-152.</unstructured_citation>
</query>
</body>
</query_batch>
- Search for a content item using structured metadata:
https://doi.crossref.org/servlet/query?usr=email@address.com&qdata=<?xml version = "1.0" encoding="UTF-8"?>
<query_batch xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="2.0"
xmlns="http://www.crossref.org/qschema/2.0" xsi:schemaLocation="http://www.crossref.org/qschema/2.0 http://www.crossref.org/qschema/crossref_query_input2.0.xsd">
<head>
<email_address>support@crossref.org</email_address>
<doi_batch_id>my_batch_label</doi_batch_id>
</head>
<body>
<query key="1178517" enable-multiple-hits="false" forward-match="false">
<issn match="optional">15360075</issn>
<journal_title match="exact">American Journal of Bioethics</journal_title>
<author match="fuzzy" search-all-authors="false">Agich</author>
<volume match="fuzzy">1</volume>
<issue>1</issue>
<first_page>50</first_page>
<year>2001</year>
<article_title>The Salience of Narrative for Bioethics</article_title>
</query>
</body>
</query_batch>
- Retrieve forward links using the forward link endpoint:
https://doi.crossref.org/servlet/getForwardLinks?usr=email@address.com/role&pwd=password&doi=10.1021&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD
- Retrieve forward links using XML query:
https://doi.crossref.org/servlet/query?usr=ROLE&pwd=PASSWORD&qdata=<?xml version="1.0"?>
<query_batch version="2.0" xmlns = "http://www.crossref.org/qschema/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.crossref.org/qschema/2.0 http://www.crossref.org/qschema/crossref_query_input2.0.xsd">
<head>
<email_address>EMAIL</email_address>
<doi_batch_id>my_batch_label</doi_batch_id>
</head>
<body>
<fl_query alert="false">
<doi>10.1021/acs.joc.7b01326</doi>
</fl_query>
</body>
</query_batch>
In this request fl_query_alert allows the requester to receive email or endpoint notification alerts for subsequent references to the work.
The XML API returns metadata in UNIXSD or UNIXREF format. The format can be specified in the request. The output for the forward links endpoint is the query output schema.
Note that in the forward links output, the field fl_count refers to the number of times the referencing item has itself been referenced.
Character encoding
Some characters must be URL-encoded to ensure that requests work correctly:
| Character | Name | URL code |
|---|
| ; | Semi-colon | %3B |
| / | Slash, virgule, separatrix, or solidus | %2F |
| ? | Question mark | %3F |
| : | Colon | %3A |
| @ | At sign, arobase | %40 |
| = | Equals sign | %3D |
| & | Ampersand | %26 |
| lf | line feed | %0A |
Endpoints
The base URL for the XML API is https://doi.crossref.org. The following endpoints are available:
DOI lookup
To find metadata for a single DOI, use the endpoint https://doi.crossref.org/search/doi. One of the pid and usr parameters is required, and one of doi and pubid must also be used.
Up to 2025, some members could also add a pwd parameter combined with a unique username to specify a password and perform their DOI lookups. This is not required anymore and you only need to add pid or usr.
Metadata Plus subscribers should use the following header with their API token:
Crossref-Plus-API-Token: Bearer [FullTokenHere]
| Parameter name | Values and examples | Description |
|---|
usr | email@address.com | Identify yourself so that we can contact you in case of any issues with your requests. |
pid | email@address.com | An alternative to the usr field. |
doi | 10.1577/H02-043 | DOI of a content item. |
pubid | J173705 | Record type and journal ID. See below*. |
format | unixsd or unixref | XML format for the response. See UNIXSD and unixref. The default is UNIXSD v2.0. Including unixref gives the response in v3.0. |
*pubid can be used to retrieve content items in a title, such as a journal or book. The value starts with a single letter defining the record type: J for journals, B for books or conference proceedings, S for series. This is followed by the publication ID of the title.
Query
To find one or more matching DOIs based on some input metadata, use the endpoint https://doi.crossref.org/servlet/query. Note, however, that the REST API also provides a query parameter and is typically more straightforward to use.
One of pid and usr is required. See query schema for how to construct a query. Metadata Plus subscribers should use the following header with their API token:
Crossref-Plus-API-Token: Bearer [FullTokenHere]
Any special characters, such as accents or symbols, in values included in qdata should be HTML encoded to ensure the correct results. For example, replace á with á.
| Parameter name | Values and examples | Description |
|---|
usr | email@address.com | Identify yourself so that we can contact you in case of any issues with your requests. |
pid | email@address.com | An alternative to the usr field. |
id | 10.1577/H02-043 | Optional. DOI of a content item. |
doi | 10.1577/H02-043 | Optional. Alternative to the id field. |
qdata | See query schema | Required. An XML query using the UNIXSD query format. The <query> field is repeatable and up to five queries can be made in one request. |
format | unixsd, unixref, or info | Output format for the response. See UNIXSD and UNIXREF. info includes selected crm-items from UNIXSD. The default is UNIXSD v2.0. Including unixsd gives the response in v3.0. |
Forward links
The endpoint https://doi.crossref.org/servlet/getForwardLinks allows members to retrieve bibliographic information of content items that reference theirs. This information is called forward links. Member login credentials (email address, role, and password) are required to access this endpoint.
| Parameter name | Values and examples | Description |
|---|
usr | email@address.com/my_role | Required. Email address and user role. |
pwd | my_password | Required. Password for the user account. |
doi | 10.1577/H02-043, 10.1577 | DOI or DOI prefix that you would like to retrieve results for. |
date | YYYY-MM-DD | Date for which to retrieve forward links. |
include_postedcontent | true or false (default) | Include references from posted content (e.g., preprints and theses). |
