Ticket of the month - March 2022 - Getting started with REST API queries

Our REST API is largely used for retrieval of metadata by machines. But, there are some manual queries that can be performed by you or me to retrieve metadata. Let’s take a look at a common question of the support team from a member looking for information about her colleagues:

I work at the Science State University and I am trying to learn how to use the Crossref API in order to retrieve data about the publications of the researchers of my institution.

In particular, I would like to retrieve the list of the publications of at least one author affiliated to Science State University. Could you please help me with this?

I always like starting with a straightforward query like this: https://api.crossref.org/works?query.affiliation=Science+State+University&select=DOI,title,author&rows=500&mailto=support@crossref.org

In this query, I am searching our whole corpus for any affiliation that includes the word Science or State or University; I am limiting the metadata that is returned to me for each DOI to:

  • DOI
  • title of the work
  • the contributor/author list for that DOI

The results are in order of relevance to the query affiliation, so the top results will have a higher match or relevance score for the words Science+State+University than the results down the page. By adding my email address, I can identify myself and thus access the Polite pool of the REST API (you can omit it, if you need to stay anonymous, which will result in querying our Public pool).

Let’s say that I also want the cited-by counts of those same DOIs that I received in my results above. I’d simply add the is-reference-by-count parameter to my query:

https://api.crossref.org/works?query.affiliation=Science+State+University&select=DOI,title,author,is-referenced-by-count&rows=500&mailto=support@crossref.org

We, Crossref staff, keep a list of some of the more useful queries that members and metadata users have sent to or requested of us. I thought it worthwhile to share these with you. You’ll see those below with a brief explanation of the query. It’s also important to note that, if you’re interested in getting started with constructing your own REST API queries, you can use the functionality with our REST API documentation (Swagger) to assist.


Some of the more common REST API query requests we see:

All works on a particular prefix: https://api.crossref.org/prefixes/10.35195/works

Article titles on a particular prefix: https://api.crossref.org/prefixes/10.35195/works?select=DOI,title

If you want the journal title too, it’s: https://api.crossref.org/prefixes/10.35195/works?select=DOI,container-title,title

Which DOIs for a specific prefix have license information deposited for them?
https://api.crossref.org/prefixes/10.1098/works?filter=has-license:true&rows=300 (300 results at a time)

All works by title for a prefix:
https://api.crossref.org/prefixes/10.21240/works?select=DOI&rows=1000

All works for this ISSN sorted with these elements DOI, title, volume, issue and page number (first 20 results returned):
https://api.crossref.org/journals/1527-2095/works?select=DOI,title,volume,issue,page

All works for this ISSN sorted with these elements DOI, title, volume, issue and page number (first 1000 results returned):
https://api.crossref.org/journals/1527-2095/works?select=DOI,title,volume,issue,page&rows=1000

All works registered with a specific ORCID iD:
https://api.crossref.org/works?filter=orcid:0000-0002-9117-4510

All works registered with a specific ORCID iD with results sorted with only the following metadata: DOI, title, and citation count:
https://api.crossref.org/works?filter=orcid:0000-0002-9117-4510&select=DOI,title,is-referenced-by-count

All chapter-level DOIs registered against an ISBN with the results sorted with elements DOI, title, type, container (book-level) title, links, and ISBN:
https://api.crossref.org/works?filter=isbn:9783030814649&select=DOI,title,ISBN,type,container-title,link&rows=100

List of DOI counts registered against a prefix and the type of content registered for those DOI counts:
https://api.crossref.org/prefixes/10.37670/works?rows=0&facet=type-name:*

What is the most recently deposited DOI that has been indexed in the REST API on a particular prefix Today: https://api.crossref.org/prefixes/10.1021/works?filter=from-created-date:2021-05-14,until-created-date:2021-05-14&sort=deposited&order=desc

Overall:
https://api.crossref.org/prefixes/10.1021/works?sort=deposited&order=desc

Show me who is registering grants:
https://api.crossref.org/types/grant/works?rows=0&facet=funder-name:*

List of top 10 (and, 1000) most-cited DOIs for a prefix (results limited to DOI, title, and citation count):
https://api.crossref.org/prefixes/10.1001/works?sort=is-referenced-by-count&select=DOI,title,is-referenced-by-count&order=desc&rows=10

https://api.crossref.org/prefixes/10.1001/works?sort=is-referenced-by-count&select=DOI,title,is-referenced-by-count&order=desc&rows=1000

Works created between two dates:
https://api.crossref.org/prefixes/10.31356/works?rows=100&filter=from-created-date:2020-01-01,until-created-date:2020-12-31

All DOIs registered with the isTranslationOf relation: https://api.crossref.org/works?filter=relation.type:is-translation-of

I should also note, if you are eager to get started with manual queries and you do not have a JSON formatter installed in the browser of your choice, now might be the time to reconsider that. I use this extension for Google Chrome, but there are other extensions and other browsers, so I encourage you to find one that is right for you: JSON Formatter - Chrome Web Store

Let us know what you think. Thanks for reading!

-Isaac

3 Likes

Thanks for this excellent post. A few examples for query.bibliographic, and the concept of paths (e.g other than the “works” path) would be nice for your future post.

Regards

1 Like

Hi @psmku,

Thank you!

I’ve included a few examples of query.bibliographic queries and some information about the paths (or, resource components) below. Let me know what you think, or if you have any follow-up questions or comments.

Bibliographic queries
I am looking for all grants including the award number 7196:
https://api.crossref.org/works?query.bibliographic=7196&filter=type:grant

Also grants-related. I’m searching for all grants that include the project title RIZ1:
https://api.crossref.org/works?query.bibliographic=RIZ1&filter=type:grant

In this query, I’m searching for all works that include island, biogeography, or Wilson. Ideally, I’m hoping to find content by E.O. Wilson on island biogeography. My results will be sorted in order of relevance with the top results including all three words in the bibliographic metadata (i.e., query.bibliographic information, useful for citation look up, includes titles, authors, ISSNs and publication years):
https://api.crossref.org/works?query.bibliographic=island+biogeography+Wilson

Paths (or, resource components)
Major resource components supported by the Crossref API are:

  • works
  • funders
  • members
  • prefixes
  • types
  • journals

These can be used alone like this

resource description
/works returns a list of all works (journal articles, conference proceedings, books, components, etc), 20 per page
/funders returns a list of all funders in the Funder Registry
/members returns a list of all Crossref members (mostly publishers)
/types returns a list of valid work types
/licenses return a list of licenses applied to works in Crossref metadata
/journals return a list of journals in the Crossref database

Resource components and identifiers

Resource components can be used in conjunction with identifiers to retrieve the metadata for that identifier.

resource description
/works/{doi} returns metadata for the specified Crossref DOI.
/funders/{funder_id} returns metadata for specified funder and its suborganizations
/prefixes/{owner_prefix} returns metadata for the DOI owner prefix
/members/{member_id} returns metadata for a Crossref member
/types/{type_id} returns information about a metadata work type
/journals/{issn} returns information about a journal with the given ISSN

Combining resource components

The works component can be appended to other resources.

resource description
/works/{doi} returns information about the specified Crossref DOI
/funders/{funder_id}/works returns list of works associated with the specified funder_id
/types/{type_id}/works returns list of works of type type
/prefixes/{owner_prefix}/works returns list of works associated with specified owner_prefix
/members/{member_id}/works returns list of works associated with a Crossref member (deposited by a Crossref member)
/journals/{issn}/works returns a list of works in the given journal

Warm regards,
Isaac

1 Like

Congratulation Isaac !!

Another excellent follow-up post. I appreciate this effort from the core of my heart.
The section on Combining resource components is extremely helpful for me and my students here.

Another confusing concept in Crossref (as reported by students) is the application/combination of rows and offset.

For example,

https://api.crossref.org/works?query.bibliographic=LGBT+LGBTQ+LGBTQI+LGBTQIA&filter=type:book-chapter,type:journal-article&select=DOI,title,subtitle,container-title,type,ISBN,ISSN,publisher,publisher-location,published-print,published-online,is-referenced-by-count,references-count,abstract,subject&rows=1000&offset=0

will retrieve the first set (keeping in view the limitation of 1000 results per call).

Then I always find it difficult for students to understand that to retrieve the second set we need to change values of rows and offset as rows=1000&offset=1000.

A few examples on this issue will be very helpful for users like us.

Best regards

Hi @psmku,

For the query:

https://api.crossref.org/works?query.bibliographic=LGBT+LGBTQ+LGBTQI+LGBTQIA&filter=type:book-chapter,type:journal-article&select=DOI,title,subtitle,container-title,type,ISBN,ISSN,publisher,publisher-location,published-print,published-online,is-referenced-by-count,references-count,abstract,subject&rows=1000&offset=0

there are over 10,000 results. Offsets for /works are limited to 10,000, so using offsets here is not recommended. Instead, you should be using cursor. See more details on this distinction below.

Offset

The number of returned items is controlled by the rows parameter, but you can select the offset into the result list by using the offset parameter. So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:

https://api.crossref.org/works?query=allen+renear&rows=5&offset=5

Offsets for /works are limited to 10K. Use cursor (see below) for larger /works results sets.

Deep paging with cursors

Using large offset values can result in extremely long response times. Offsets in the 100,000s and beyond will likely cause a timeout before the API is able to respond. An alternative to paging through very large result sets (like a corpus used for text and data mining) is to use the API’s exposure of Solr’s deep paging cursors. Any combination of query, filters and facets may be used with deep paging cursors. While rows may be specified along with cursor, offset and sample cannot be used. To use deep paging make a query as normal, but include the cursor parameter with a value of *. In this example we will page through all journal-article works from member 311:

https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=*

A next-cursor field will be provided in the JSON response. To get the next page of results, pass the value of next-cursor as the cursor parameter. For example:

https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=AoE/CGh0dHA6Ly9keC5kb2kub3JnLzEwLjEwMDIvdGRtX2xpY2Vuc2VfMQ==

Note that the actual cursor value will be different from this illustration.

Clients should check the number of returned items. If the number of returned items is fewer than the number of expected rows then the end of the result set has been reached. Using next-cursor beyond this point will result in responses with an empty items list.

The cursor parameter is available on all /works resources.

My best,
Isaac