crossrefapi Python Library

To follow Crossref API etiquette, create an Etiquette object and pass it to the endpoint class (e.g., Works). This sets a custom User-Agent header that identifies your project, version, URL, and contact email, which is recommended for responsible API usage.

from crossref.restful import Works, Etiquette

# Define your project identity
my_etiquette = Etiquette(
    'My Project Name', 
    'My Project version', 
    'My Project URL', 
    'My contact email'
)

# Pass etiquette to the client
works = Works(etiquette=my_etiquette)

# Use the client as normal
for i in works.sample(5).select('DOI'):
    print(i)

Install the library using the standard Python package manager.

pip install crossrefapi

To follow Crossref's best practices (etiquette), you can provide metadata about your application. This information is sent in the User-Agent header, which helps Crossref identify your requests and contact you if necessary. This is highly recommended for stable and polite API usage.

from crossref import Etiquette

etiquette = Etiquette(
    application_name="my_research_app",
    application_version="1.0.0",
    application_url="https://example.com",
    contact_email="dev@example.com"
)
# Pass this etiquette object when initializing your API client

When using methods that support filtering (like query or filter on certain endpoints), you can refine results using keyword arguments.

Important: Parameter Naming Convention Because Crossref API filter names may contain special characters, you must transform them for Python keyword arguments:

• Replace dots (.) with double underscores (__)
• Replace dashes (-) with single underscores (_)

Example: A filter named has-public-references must be passed as has_public_references=True.

To follow Crossref's polite request guidelines (Etiquette), you can pass an Etiquette object when initializing the Depositor. This identifies your project and provides contact information to Crossref.

Required fields for Etiquette:

• Project Name
• Project Version
• Project URL
• Contact Email

from crossref.restful import Depositor, Etiquette

etiquette = Etiquette('My Project Name', 'My Project version', 'My Project URL', 'My contact email')
depositor = Depositor('your prefix', 'your crossref user', 'your crossref password', etiquette)

You can chain .filter() and .select() methods to refine your search results.

• Filtering: Use Works.FILTER_VALIDATOR to find valid parameters. When using parameters in Python, replace dots (.) with double underscores (__) and hyphens (-) with underscores (_).
• Selecting: Use Works.FIELDS_SELECT to specify which fields to return. You can pass a single string or a list of strings.

from crossref.restful import Works

works = Works()

# Filter by license URL and publication year, take a sample, and select only the 'title' field
for i in works.filter(license__url='https://creativecommons.org/licenses/by', from_pub_date='2016').sample(5).select('title'):
    print(i)

# Selecting multiple specific fields
for i in works.filter(has_funder='true', has_license='true').sample(5).select(['DOI', 'prefix']):
    print(i)

The .count() method returns the total number of items a query result should retrieve (the total-results attribute from the API). It does not iterate through or fetch the actual documents, making it a lightweight way to check result sizes.

from crossref.restful import Works

works = Works()
# Count total works matching a query
count = works.query('zika').count()

# Count works matching a query and a filter
filtered_count = works.query('zika').filter(from_online_pub_date='2017').count()

Faceting allows you to see the distribution of values for a specific field (like issn) within a result set.

• Works.facet(field, limit): Returns facets for the entire Crossref database.
• Prefixes.works(prefix).facet(field, limit): Returns facets for works belonging to a specific DOI prefix.
• Prefixes.works(prefix).query(term).facet(field, limit): Returns facets for works matching a query within a specific prefix.

from crossref.restful import Works, Prefixes

# Global facet
works = Works()
print(works.facet('issn', 10))

# Facet within a specific prefix
prefixes = Prefixes()
print(prefixes.works('10.1590').facet('issn', 10))

# Facet within a query inside a specific prefix
print(prefixes.works('10.1590').query('zika').facet('issn', 10))

Use Works.sample(n) to retrieve a random sample of n items from the current result set or query.

from crossref.restful import Works

works = Works()
for item in works.sample(2):
    print(item['title'])

The .url method returns the exact URL that will be used to query the Crossref API. This is useful for debugging complex queries involving .query(), .filter(), .sort(), and .order().

from crossref.restful import Works

works = Works()
# Inspect a complex URL construction
url = works.query('zika').filter(from_online_pub_date='2017').query(author='Mari').sort('published').order('asc').url
print(url)