DOCSEARCHbyAlgolia
Submit Docs

Crossref REST API Documentation

repository·master·Indexed 21 days ago

https://github.com/crossref/rest-api-doc

Documentation for the Crossref REST API, providing access to bibliographic metadata and Digital Object Identifiers (DOIs). Includes details on resource components (/works, /funders, /members), query and filter parameters, rate limiting, and API etiquette. Note: This specific documentation is deprecated as the API transitioned from Solr to Elasticsearch; users are directed to api.crossref.org for the most current details.

Tokens
19.9K
Snippets
43
Records
70
Agent score
73%

What's inside Crossref REST API

  1. API Overview and URL Encoding Requirements

    master

    The Crossref REST API is RESTful and returns results in JSON format with the mime-type application/vnd.crossref-api-message+json. The API supports both HTTP and HTTPS (HTTPS is recommended).

    Critical Requirement: You must always url-encode DOIs and all parameter values. DOIs frequently contain characters that break URLs, such as semicolons (;), hashes (#), slashes (/), ampersands (&), and question marks (?). This also applies to cursor values, which may contain + symbols.

  3. Understand the Date and Partial Date formats

    master

    Crossref uses two distinct date formats for metadata:

    1. Date: A full timestamp including year, month, and day.

      • date-parts: An array of numbers [ [ year, month, day ] ] (conforming to citeproc JSON dates).
      • timestamp: UNIX epoch seconds.
      • date-time: ISO 8601 string.

    2. Partial Date: Used when only certain components of a date are known.

      • date-parts: An array of numbers [ [ year, month, day ] ]. Only year is strictly required.
    ### Date
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| date-parts | Array of Number | Yes | Contains an ordered array of `year`, `month`, `day of month`. Note that the field contains a nested array, e.g. `[ [ 2006, 5, 19 ] ]` to conform to citeproc JSON dates |
| timestamp | Number | Yes | Seconds since UNIX epoch |
| date-time | String | Yes | ISO 8601 date time |

### Partial Date
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| date-parts | Array of Number | Yes | Contains an ordered array of `year`, `month`, `day of month`. Only `year` is required. Note that the field contains a nested array, e.g. `[ [ 2006, 5, 19 ] ]` to conform to citeproc JSON dates |

  4. How to access the 'Polite Pool' of API machines

    master

    Crossref provides a dedicated pool of machines for 'polite' users to ensure better performance and reliability. To be directed to this pool, you must use HTTPS and provide contact information using one of the following two methods:

    1. Include a mailto parameter in your query: https://api.crossref.org/works?filter=has-full-text:true&mailto=GroovyBib@example.org

    2. Include a mailto: in your User-Agent header: GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org) BasedOnFunkyLib/1.4

    Providing contact information allows Crossref to reach out if your script causes service disruptions. If you provide incorrect contact info and fail to respond to issues, you may be blocked.

    GET /works?filter=has-full-text:true&mailto=GroovyBib@example.org HTTP/1.1
Host: api.crossref.org

  5. Understand API Result Types: Singletons, Headers-only, and Lists

    master

    The API returns three types of results:

    1. Singletons: A single result for a specific identifier (e.g., a specific DOI, ISSN, or funder_identifier). The message-type for these is typically funder, prefix, member, or work.
    2. Headers-only: By using an HTTP HEAD request, you can quickly check if a singleton exists. A 200 status means it exists; a 404 means it does not. This is faster as it avoids downloading metadata.
    3. Lists: Results containing multiple entries (e.g., from a search or filter). A list includes a Summary (status, message-type, message-version) and Items (the actual data). List message-type values include work-list, funder-list, prefix-list, and member-list.

  7. Interpret license and resource metadata attributes

    master

    When consuming Crossref metadata, use the following interpretations for missing attributes:

    • <license_ref> with no start_date: The license applies from the earliest publication date.
    • <license_ref> with no applies_to: The license applies to all <resource> elements in the record.
    • <resource> with no content_version: The resource points to the version of record ('vor').

    Note: If there is a mismatch between existing applies_to attributes and content_version attributes, it likely indicates a metadata deposit error by the publisher.

  8. Important notes on DOI prefixes and Member IDs

    master

    When querying for works published by a specific organization, use member IDs and the /members route rather than prefixes.

    • A DOI prefix reflects who originally registered the DOI, not necessarily the current owner.
    • The owner_prefix element in Crossref metadata records the current owner.
    • A single member may control multiple owner prefixes.

  9. Use dot filters for related record types

    master

    A filter containing a dot (.) in its name is a special filter applied to a related record type. For example, when querying /works, you can filter by properties of an associated award record using award.number or award.funder.

    /works?filter=award.number:CBET-0756451,award.funder:10.13039/100000001

  10. Choose the appropriate Crossref API service level

    master

    Crossref offers three levels of access to the REST API, providing different balances of anonymity and reliability:

    1. Public (Anonymous): Free and anonymous access. Traffic patterns vary wildly and it is harder for Crossref to contact users if scripts cause issues.
    2. Polite (Self-identification): Free access where you include contact information in your requests. This redirects requests to a more reliable "Polite" pool of servers and allows Crossref to contact you if your scripts cause system problems. Contact info is kept in logs for 90 days.
    3. Plus (Authenticated): A paid service providing an authentication token. This directs requests to a reserved pool of servers designed for high predictability and production services.

  11. Perform partial metadata deposits

    master
    Partial deposits (also known as resource deposits) allow you to update specific parts of a DOI's metadata rather than the entire record. You can deposit licenses, funding information, CrossMarks, or resource links partially. Multiple partial deposits for different types of metadata (or even multiple updates for the same DOI) can be included in a single batch within the <body> element.

  12. Record license information using `<license_ref>`

    master

    Publishers must use the <license_ref> element to record how research is licensed. This is critical for funders tracking the public availability of research results.

    Rules for <license_ref>:

    • The value must be a stable HTTP URI pointing to a human-readable document containing copyright or licensing information (e.g., a Creative Commons deed or a publisher's proprietary license page).
    • You can deposit multiple <license_ref> elements to indicate dual licensing (e.g., different licenses for commercial vs. non-commercial use).
    • It is acceptable to use a "placeholder" URI (pointing to a blank page or copyright re-assertion) if specific terms are still being finalized, as this indicates intent to clarify rather than leaving the status ambiguous.
    <!-- CC-BY license example -->
<license_ref>http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>

<!-- Proprietary license example -->
<license_ref>http://www.psychoceramics.org/license_v1.html</license_ref>

<!-- Dual license example -->
<license_ref>http://www.psychoceramics.org/non_commercial_license_v1.html</license_ref>
<license_ref>http://www.psychoceramics.org/commercial_license_v1.html</license_ref>