crossref
A client for the CrossRef API, for Node and browsers.
The CrossRef API is relatively simple, but rolling access by hand is
never fun; and it has its little inconsistencies that can bite you. This thin module wraps it so
that you don't have to worry about that too much. (I say “too much” because it does not remove
inconsistency down to the object level, e.g. things sometimes being uri
and sometimes URL
.)
Installation
The usual:
npm install --save crossref
API
Details for the API and the objects can be obtained from the official CrossRef
documentation. It isn't very thorough (to say the least) but accessing
various endpoints with ?sample=10
tacked onto the URL should give you a decent idea of what the
objects look like. (If you want to know which fields are optional and which are guaranteed to occur
you're out of luck, though, there is no documentation whatsoever — and I know no better).
You can load the CrossRef object like this:
import CrossRef from 'crossref';
If you're somehow reading this before 2015, you can also do:
var CrossRef = require('crossref')
In the browser you load crossref.min.js
, then access the global CrossRef
object.
This module exposes two types of methods: item methods, that only ever return one object, and
list methods that return a list of objects followed by several bits of information that can be
used to work with the list, notably with pagination. They differ in their callbacks:
- The item method callbacks receive
(err, obj)
where err
is an Error
(if there was one), and
obj
will be a simple JSON data structure. - The list method callbacks receive
(err, objects, nextOptions, isDone, message)
. That may seem
like a mouthful, but you rarely need them all. As usual err
is an Error
if there was one,
and objects
is a list of simple JSON data structures. When you are paginating through the
results (which is not uncommon since CrossRef is a relatively large database) you will want to
use nextOptions
and isDone
. The former is an options object that captures the same search
options you passed to the method, but with the offset
adjusted such that it will get the next
page. Basically, if you call the same method again with nextOptions
you will get the next page
of the same query. And the latter is a boolean that is true
if you have reached the last page.
Finally, message
is just the list wrapper without its objects; it is only really useful if you
need some obscure metadata, for instance if you are doing a facet
query (if you don't know what
that is you probably don't need it).
Root Listing Methods
These query the root endpoints from the CrossRef API and return a list. They all take an optional
options
object. If it is empty you just list everything, if it is defined it will translate to
the API's parameters.
Only minimal process is done to map your JS object to the query string:
- If you have a
query
, it is properly escaped. - You can specify
filter
as an object, and the correct string is built for you. If you want to
specify a given filter key multiple times to OR
it, just put all the values in an array. - If you set
facet
to any truthy value it will come out as facet=t
.
Other options are just past through as key-value pairs. The options object can always be omitted.
You might want to be cautious with options
on the types()
method: the API tends to behave
differently for that endpoint, and while we try to make it more consistent we probably haven't
caught everything yet.
The methods are documented in the
API:
CrossRef.works([options], listCB)
CrossRef.funders([options], listCB)
CrossRef.members([options], listCB)
CrossRef.types([options], listCB)
CrossRef.licenses([options], listCB)
CrossRef.journals([options], listCB)
Item Methods
These methods retrieve a single item for a given key (or return an Error
if not found). They are
documented in the
API
CrossRef.work(doi, itemCB)
CrossRef.funder(funderID, itemCB)
CrossRef.prefix(doiPrefix, itemCB)
CrossRef.member(memberID, itemCB)
CrossRef.type(typeID, itemCB)
CrossRef.journal(issn, itemCB)
Works Listing Methods
These methods are listing methods, but they list the works that correspond to a given item (e.g.
the works funded by a given funder). They all take a key like the item methods and optional
options
. They are documented in the
API.
CrossRef.funderWorks(funderID, [options], listCB)
CrossRef.prefixWorks(doiPrefix, [options], listCB)
CrossRef.memberWorks(memberID, [options], listCB)
CrossRef.journalWorks(issn, [options], listCB)