Using OAI PMH citation query to return DOIs that have received citations during specified timeframe (example)

Submitted by: Robert Feb 11 14:40

Is there an API for pulling data about DOI resolutions?

Isaac Farley , Crossref support, responded Feb 11 16:21

Hi Robert,

Thanks for your message. No, we do not have an API for pulling data about DOI resolutions. The only information we provided on DOI resolutions is the resolution report that we send monthly to the contacts on your account who have been enabled to receive the report. As the business contact on the 10.21061 prefix, you should receive these to your email inbox during the first week or two of each month.

Please let me know if you have any additional questions.

Kind regards,

Isaac Farley
Crossref Technical Support Manager

Keep up to date with service performance, incidents, and planned maintenance at

Submitted by: Robert Feb 11 16:32

Thanks, Isaac. I do get the resolution reports. We love them!!!

We use resolution reports to create impact metrics for our publications. It would be great to have a way to automate the organization of that information. Do you have any idea of how other members manage resolution info?

Thanks again,

Isaac Farley , Crossref support, responded Feb 11 16:51

Oh, I’m glad you like them, Robert. We’re eager to improve their utility too, albeit I don’t know that those improvements are going to come as quickly as I would like (given other priorities that we’re currently balancing).

All I have is anecdotal information about how our members use the resolution reports. Most of the members I know use the top 10 list of DOIs to get an idea of what’s most popular from month-to-month. Many members use the resolution report and an analytics tool, like Google Analytics, to get a more complete picture of traffic to their content. That resolution failure csv is popular amongst members who are investigating issues with either their content registration process or publication workflow. I think I found that bit of the report most useful back when I was with a Crossref publisher. Those failures highlighted problems in our own process that were allowing resolutions to DOIs (failures) that had not yet been registered with Crossref. It turns out that it was an issue of timing. We were distributing DOIs to authors, reviewers, and ourselves too early in the process. We corrected that and our failures improved.

Can you let me know more about how the information could be organized better to benefit you? Again, no promises that any improvements will come swiftly, but we are interested in improving this report and others. We have some ideas, but I’m curious what you think.

Looking forward to your ideas,

Submitted by: Robert Feb 24 10:12

Sorry to be so slow in responding. Thanks so much for your interest in this topic!

I’ll begin by telling you a bit about our operating environment. We are a library publisher. We publish journals and books. We also have an institutional repository (IR) with mandatory deposit requirements for thesis and dissertations. We currently only use DOI for objects that do not live in the IR, since the IR uses a handle system. The University as a whole has been busy over the past few years revamping its reporting metrics. This of course includes the library. Libraries typically track interactions, references, and consultations and our library does too. So, the publishing department reports those types of metrics like all other library departments. However, as a publisher it’s also important for us to report impact metrics from our publications that demonstrate some sort of return on investment. This year I plan to track just a handful of impact metrics for our publications with DOI:

  • Total number of citations
  • Total number of DOI resolutions
  • Total number of PDF downloads
  • Total number of page views or more than 30 seconds in duration

Of these metrics the number of citations is assumed to have the greatest impact, DOI resolutions is second, PDF download is third, and page views of greater than 30 seconds is fourth. To gather this information we use a combination of Crossref and Google Analytics (GA). We currently pull all this information together semi-manually using spreadsheets and manual data entry. We have a number of different GA properties, but do not yet have an automated way to aggregate reports for all GA properties.

The number of citations comes from Cited By, which I have just recently learned to query using the URL string. Is there an API for Cited By? I really wish I could pull a single number for citations for all of our publications within a given date range. That would be super helpful! If there is a way to do this, please let me know : )

The number of DOI resolutions comes from our monthly Crossref reports. Of all the metrics gathering we do, this is the least amount of work for us to pull together.

I hope this is informative. Please let me know if you have specific questions or would like to chat about metrics gathering sometime.

Best always,

Isaac Farley , Crossref support, responded Feb 24 15:28

Hi Robert,

Thanks for your message. I appreciate all the information you have shared about how you gather and use metrics. That’s all very helpful.

I agree with your hierarchy of importance - and that citations should be the given the most weight. You can use our cited by service (your prefix is already active and enabled for cited by) to retrieve information about your DOIs. Full instructions on retrieving cited by matches is available here:

Thanks again for your thoughtful response,

Submitted by: Robert Feb 25 10:57

Hi Isaac,

Thanks for your response. I’ve been learning to work with CIted By using the OAI URL query strings. When I query for a specific date range I see results in the output that are not within the specified date range. For instance, I put in this query string and the response (copied in attached txt file) contains items that are outside the date range. Perhaps I am not forming my query correctly? Is there something else I should be aware of when querying based on date range?

My query:[username]&pwd=[password]&set=J:10.21061:300318&from=2019-07-01&until=2019-12-31&metadataPrefix=cr_citedby


Isaac Farley , Crossref support, responded Feb 25 14:21

Hi Robert,

Thanks for this specific example. It looks like your query is well formed. My initial reaction is that perhaps something is wrong on our end, but let me discuss this with my colleagues on the support team tomorrow during our stand up to see if we have a consensus. If they agree, I’ll elevate this to our tech team for investigation.

More soon,

Isaac Farley , Crossref support, responded Mar 18 15:17

Hi Robert,

Apologies for the slow response time here. I spoke with Jon on our tech team, who understands the inner-workings of OAI-PMH better than me:


So the OAIHandler/ListRecords request has an interesting implementation regarding dates.

The date range query is matching any cited-by relationships that have been updated within the date range in which the target DOI (the one being cited) is in the setspec.

So if you, as a publisher, are querying the cited-by relations of YOUR DOI, it does not matter what the update date of YOUR DOI is. If ANY DOI that “cites” YOUR DOI was updated during the time-frame, YOUR DOI and ALL DOIs citing YOUR DOI will be returned (regardless of any of the other dates) because the cited-by relations for YOUR DOI have in fact changed during that time-frame.


This one is essentially the same as the previous one except that this ONLY shows 10.21061/jte.v26i2.a.2 and the ONE citer (10.1111/ssm.12376) that changed during the date range. It omits the other DOIs for that journal since only the one DOI was queried but the data for the given DOI is the same in both results.


This one only queries the one DOI and omits a date range so this shows all 13 relations just as the first OAIHandler request does, though the format is somewhat different.

Please let me know what you think of these responses. At a minimum, I think we need to update our documentation to better explain this, but I’m going to be discussing with our product team if our setup is exactly how we expect it to be or if we need to make any tweaks.

Thanks for surfacing this. I look forward to hearing from you with your thoughts.

Best regards,

Submitted by: Robert Mar 24 13:29

This is a great answer and gives me just what I need to know. Although the behavior of Cited-By is not what I thought it was, I am sure it will prove helpful in many ways.

If I could do one query that would return all time citations for all of our publications as a single number that would be awesome! I would probably run such a query twice a year for semi-annual impact metrics gathering. I still really appreciate that we can drill down into citations for each publication. But having a single number of all-time citations to include in reports to deans and provosts is really helpful. It’s a quick way to communicate return on investment to budgetary decision makers.

Thank you so much!


Isaac Farley , Crossref support, responded Mar 24 14:54

While this API query does not included cited-by numbers, it may be helpful for other stats: (this is your member ID)

Also, do these queries give you annual or semi-annual data that you can use for the prefix as a whole? As you can see, the queries return lots of data, so you may wish to run them quarterly:[username]&pwd=[password]&doi=10.21061&startDate=2019-01-01&endDate=2019-12-31[username]&pwd=[password]&doi=10.21061&startDate=2020-01-01&endDate=2020-03-22

Looking forward to hearing back from you,

Submitted by: Robert Mar 25 10:20

Thank you for these additional queries. I think they will be helpful for compiling annual impact metrics. Although, we may have to develop a script to parse the results. Or perhaps I can figure something out something out with Open Refine? In any case, I think we can manage it : )

Best always,

Isaac Farley , Crossref support, responded Mar 25 15:07

I’m not familiar with Open Refine (although I just did a quick search and it looks promising), but you should be able to develop a script to parse the results you need from our API. As always, let us know if you have questions along the way.

Kind regards,