PID Graph GraphQL Example All Citations

User story

As a researcher or infrastructure provider, I want to see all citations and references to a given DOI including traditional citation, Twitter, blogs and grey literature.

Query strategy

Starting with the DOI for the publication, we fetch the metadata about the publication we are interested in, its citations and whatever metadata we want from the citing resources.

The citations we provide are either other Crossref DOIs, or DataCite DOIs using the relation types cites, references, and isSupplementTo. The latter includes grey literature. The GraphQL API does not (yet) include Twitter or blogs (other than the small number that use DOIs).

Why GraphQL

We can return metadata about the cited resource and the citing resources in one query. We can also return additional information, in this case formatted citations in the Vancouver citation style.

In this example, 47 citations are returned as of April 12, 2020.

Use the following query in the GraphQL client at https://api.datacite.org/graphql

{
  work(id: "https://doi.org/10.1001/jama.2020.2648") {
    id
    types {
      resourceType
    }
    publisher
    publicationYear
    creators {
      id
      name
      affiliation {
        name
      }
    }
    titles {
      title
    }
    citationCount
    formattedCitation(style: "vancouver")
    citations(first: 50) {
      nodes {
        id
        types {
          resourceType
        }
        publisher
        publicationYear
        creators {
          id
          name
          affiliation {
            name
          }
        }
        titles {
          title
        }
        citationCount
        formattedCitation(style: "vancouver")
      }
    }
  }
}

Related GitHub issues from 2018 FREYA workshop:

I think this addresses the user story to the extend of providing citations. I believe references can be included in the request by adding the field references in the query. But, as mentioned, at the moment, Twitter or blog links cannot be requested.

The list of citations is limited to 25 items at the moment, but I don’t see that as a problem for many use cases, e.g., look at top items.

In comparison with other APIs (Datacite REST API), this query allows accessing extra metadata, such as metadata fields of the citations and styled citation text. Other APIs are limited to retrieve PIDs and counts. However, it does seem to be a tradeoff in response time to different APIs. Probably something to work on soon.

Thanks @KristianGarza. There is a list of query parameters you can use to filter the citations, including first to specify the number of citations returned, and after for cursor-based pagination. I have updated the example query.