Readonly httpThe DOI identifier associated with the work
Returns a list of all works (journal articles, conference proceedings, books, components, etc), 20 per page.
Free form search queries can be made, for example, works that include renear or ontologies (or both):
/works?query=renear+ontologies
Field queries allow for queries that match only particular fields of metadata. For example, this query matches records that contain the tokens richard or feynman (or both) in any author field:
/works?query.author=richard+feynman
Field queries can be combined with the general query parameter and each other. Each query parameter is ANDed with the others:
/works?query.title=room+at+the+bottom&query.author=richard+feynman
This endpoint supports the following field queries:
query.affiliation - query contributor affiliationsquery.author - query author given and family namesquery.bibliographic - query bibliographic information, useful for citation look up, includes titles, authors, ISSNs and publication yearsquery.chair - query chair given and family namesquery.container-title - query container title aka. publication namequery.contributor - query author, editor, chair and translator given and family namesquery.degree - query degreequery.description - query descriptionquery.editor - query editor given and family namesquery.event-acronym - query acronym of the eventquery.event-location - query location of the eventquery.event-name - query name of the eventquery.event-sponsor - query sponsor of the eventquery.event-theme - query theme of the eventquery.funder-name - query name of the funderquery.publisher-location - query location of the publisherquery.publisher-name - query publisher namequery.standards-body-acronym - query acronym of the standards bodyquery.standards-body-name - query standards body namequery.title - query titlequery.translator - query translator given and family namesResults can be sorted by applying the sort and order parameters. sort sets the field by which results will be sorted. order sets the result ordering, either asc or desc (default is desc).
An example that sorts results in order of publication, beginning with the least recent:
/works?query=josiah+carberry&sort=published&order=asc
This endpoint supports sorting by the following elements:
created - sort by created datedeposited - sort by time of most recent depositindexed - sort by time of most recent indexis-referenced-by-count - sort by number of times this DOI is referenced by other Crossref DOIsissued - sort by issued date (earliest known publication date)published - sort by publication datepublished-online - sort by online publication datepublished-print - sort by print publication datereferences-count - sort by number of references included in the references section of the document identified by this DOIrelevance - sort by relevance scorescore - sort by relevance scoreupdated - sort by date of most recent change to metadata, currently the same as depositedFacet counts can be retrieved by enabling faceting. Facets are enabled by providing facet field names along with a maximum number of returned term values. The larger the number of returned values, the longer the query will take. Some facet fields can accept a * as their maximum, which indicates that all values should be returned.
For example, to get facet counts for all work types:
/works?facet=type-name:*
This endpoint supports the following facets:
affiliation - author affiliationarchive - archive locationassertion - custom Crossmark assertion nameassertion-group - custom Crossmark assertion group namecategory-name - category name of workcontainer-title - [max value 100], work container title, such as journal title, or book titlefunder-doi - funder DOIfunder-name - funder literal name as deposited alongside DOIissn - [max value 100], journal ISSN (any - print, electronic, link)journal-issue - journal issue numberjournal-volume - journal volumelicense - license URI of worklink-application - intended application of the full text linkorcid - [max value 100], contributor ORCIDpublished - earliest year of publicationpublisher-name - publisher name of workrelation-type - relation type described by work or described by another work with work as objectror-id - institution ROR IDsource - source of the DOItype-name - work type name, such as journal-article or book-chapterupdate-type - significant update typeFilters allow you to select items based on specific criteria. All filter results are lists.
For example:
/works?filter=type:dataset
Multiple filters can be specified in a single query. In such a case, different filters will be applied with AND semantics, while specifying the same filter multiple times will result in OR semantics - that is, specifying the filters:
is-update:truefrom-pub-date:2014-03-03funder:10.13039/100000001funder:10.13039/100000050would locate documents that are updates, were published on or after 3rd March 2014 and were funded by either the National Science Foundation (10.13039/100000001) or the National Heart, Lung, and Blood Institute (10.13039/100000050). These filters would be specified by joining each filter together with a comma:
/works?filter=is-update:true,from-pub-date:2014-03-03,funder:10.13039/100000001,funder:10.13039/100000050
A filter with a dot in its name is special. The dot signifies that the filter will be applied to some other record type that is related to primary resource record type. For example, with work queries, one can filter on works that have an award, where the same award has a particular award number and award-giving funding agency:
/works?filter=award.number:CBET-0756451,award.funder:10.13039/100000001
Here we filter on works that have an award by the National Science Foundation that also has the award number CBET-0756451.
The dates in filters should always be of the form YYYY-MM-DD, YYYY-MM or YYYY. The date filters are inclusive. For example:
from-pub-date:2018-09-18 filters works published on or after 18th September 2018from-created-date:2016-02-29,until-created-date:2016-02-29 filters works first deposited on 29th February 2016until-created-date:2010-06 filters works first deposited in or before June 2010from-update-date:2017,until-update-date:2017 filters works with metadata updated in 2017Also note that date information in Crossref metadata can often be incomplete. So, for example, a publisher may only include the year and month of publication for a journal article. For a monograph they might just include the year. In these cases the API selects the earliest possible date given the information provided. So, for instance, if the publisher only provided 2013-02 as the published date, then the date would be treated as 2013-02-01. Similarly, if the publisher only provided the year 2013 as the date, it would be treated at 2013-01-01.
The prefix of a Crossref DOI does NOT indicate who currently owns the DOI. It only reflects who originally registered the DOI. Crossref metadata has an prefix element that records the current owner of the Crossref DOI in question.
Crossref also has member IDs for depositing organisations. A single member may control multiple owner prefixes, which in turn may control a number of DOIs. When looking at works published by a certain organisaton, member IDs and the member routes should be used.
When using time filters to retrieve periodic, incremental metadata updates, the from-index-date filter should be used over from-update-date, from-deposit-date, from-created-date and from-pub-date. The timestamp that from-index-date filters on is guaranteed to be updated every time there is a change to metadata requiring a reindex.
This endpoint supports the following filters:
alternative-id - metadata for records with the given alternative ID, which may be a publisher-specific ID, or any other identifier a publisher may have providedarchive - metadata where value of archive partner equals given archive namearticle-number - metadata for records with a given article numberassertion - metadata for records with a given named assertionassertion-group - metadata for records with an assertion in a given groupawardaward.funder - metadata for records with award funder equal to given funder, optionally combine with award.numberaward.number - metadata for records with award number equal to given number, optionally combine with award.fundercategory-name - metadata for records with category label equal to given name, category labels come from the list published by Scopuscitation-idclinical-trial-number - metadata for records with given clinical trial numbercontainer-title - metadata with a publication title that exactly equals given titlecontent-domain - metadata where the publisher records a given domain name as the location Crossmark content will appeardoi - metadata describing given DOIfrom-accepted-date - [date], metadata where accepted date is since given date (inclusive)from-approved-date - [date], metadata where approved date is since given date (inclusive)from-awarded-date - [date], metadata where award date is since given date (inclusive)from-created-date - [date], metadata first deposited since given date (inclusive)from-deposit-date - [date], metadata last (re)deposited since given date (inclusive)from-event-end-date - [date], metadata where event end date is since given date (inclusive)from-event-start-date - [date], metadata where event start date is since given date (inclusive)from-index-date - [date], metadata indexed since given date (inclusive)from-issued-date - [date], metadata where issued date is since given date (inclusive)from-online-pub-date - [date], metadata where online published date is since given date (inclusive)from-posted-date - [date], metadata where posted date is since given date (inclusive)from-print-pub-date - [date], metadata where print published date is since given date (inclusive)from-pub-date - [date], metadata where published date is since given date (inclusive)from-update-date - [date], metadata updated since given date (inclusive), currently the same as from-deposit-datefull-textfull-text.type - metadata where resource element's content_type attribute equals given version mime type (e.g. application/pdf)full-text.application - [text-mining, similarity-checking or unspecified], metadata where resource link has given applicationfull-text.version - metadata where resource element's content_version attribute equals given versionfunder - metadata which include given funder id in FundRef datafunder-doi-asserted-by - metadata where funder DOI was asserted by given bodygroup-title - metadata with given group titlegte-award-amount - metadata where award is greater than or equals given numberhas-abstract - [0 or 1], metadata for records with/without an abstracthas-affiliation - [0 or 1], metadata for records with/without affiliation informationhas-archive - [0 or 1], metadata which includes/does not include name of archive partnerhas-assertion - [0 or 1], metadata for records with/without assertionshas-authenticated-orcid - [0 or 1], metadata which includes/does not include one or more ORCIDs where the depositing publisher claims to have witness the ORCID owner authenticate with ORCIDhas-award - [0 or 1], metadata for records with/without awardhas-clinical-trial-number - [0 or 1], metadata for records with/without a clinical trial numberhas-content-domain - [0 or 1], metadata where the publisher records/does not record a domain name location for Crossmark contenthas-descriptionhas-domain-restriction - [0 or 1], metadata where the publisher restricts/does not restrict Crossmark usage to content domainshas-event - [0 or 1], metadata for records with/without eventhas-full-text - [0 or 1], metadata that includes/does not include any full text resource elementshas-funder - [0 or 1], metadata which includes/does not include one or more funder entryhas-funder-doi - [0 or 1], metadata for records with/without funder DOIhas-license - [0 or 1], metadata that includes/does not include any license_ref elementshas-orcid - [0 or 1], metadata which includes/does not include one or more ORCIDshas-references - [0 or 1], metadata for works that have/don't have a list of referenceshas-relation - [0 or 1], metadata for records that either assert/do not assert or are/are not the object of a relationhas-ror-id - [0 or 1], metadata for records with/without ROR IDhas-update - [0 or 1], metadata for records with/without update informationhas-update-policy - [0 or 1], metadata for records that include/do not include a link to an editorial update policyis-update - [0 or 1], metadata for records that represent/do not represent editorial updatesisbn - metadata with given ISBNissn - metadata with given ISSN, format is xxxx-xxxxlicenselicense.url - metadata where license_ref value equals given urllicense.version - metadata where the license_ref's applies_to attribute equals given versionlicense.delay - metadata where difference between publication date and the license_ref's start_date attribute is <= than given delay (in days)lte-award-amount - metadata where award is less than or equals given numbermember - metadata belonging to a given Crossref memberorcid - metadata where there is a contributor with given ORCIDprefix - metadata belonging to a given DOI owner prefix (e.g. 10.1016)relationrelation.type - metadata for records with a relation with the given type from the Crossref relations schema (e.g. is-referenced-by, is-parent-of, is-preprint-of)relation.object-type - metadata for records with a relation, where the object type matches given type from the Crossref relations schema (e.g. doi, issn)relation.object - metadata for records with a relation, where the object identifier matches given identifierror-id - metadata with given ROR IDtype - metadata records whose type equals given type, type must be an ID value from the list of types returned by the /types resourcetype-name - metadata for records with type name equal to given nameuntil-accepted-date - [date], metadata where accepted date is before given date (inclusive)until-approved-date - [date], metadata where approved date is before given date (inclusive)until-awarded-date - [date], metadata where award date is before given date (inclusive)until-created-date - [date], metadata first deposited before given date (inclusive)until-deposit-date - [date], metadata last (re)deposited before given date (inclusive)until-event-end-date - [date], metadata where event end date is before given date (inclusive)until-event-start-date - [date], metadata where event start date is before given date (inclusive)until-index-date - [date], metadata indexed before given date (inclusive)until-issued-date - [date], metadata where issued date is before given date (inclusive)until-online-pub-date - [date], metadata where online published date is before given date (inclusive)until-posted-date - [date], metadata where posted date is before given date (inclusive)until-print-pub-date - [date], metadata where print published date is before given date (inclusive)until-pub-date - [date], metadata where published date is before given date (inclusive)until-update-date - [date], metadata updated before given date (inclusive), currently the same as until-deposit-dateupdate-type - metadata with given update typeupdates - metadata for records that represent editorial updates to given DOICrossref metadata records can be quite large. Sometimes you just want a few elements from the schema. You can "select" a subset of elements to return using the select parameter. This can make your API calls much more efficient. For example:
/works?select=DOI,prefix,title
This endpoint supports selecting the following elements.
DOIISBNISSNURLabstractacceptedalternative-idapprovedarchivearticle-numberassertionauthorchairclinical-trial-numbercontainer-titlecontent-createdcontent-domaincreateddegreedepositededitoreventfundergroup-titleindexedis-referenced-by-countissn-typeissueissuedlicenselinkmemberoriginal-titlepagepostedprefixpublishedpublished-onlinepublished-printpublisherpublisher-locationreferencereferences-countrelationscoreshort-container-titleshort-titlestandards-bodysubjectsubtitletitletranslatortypeupdate-policyupdate-toupdated-byvolumeOffsets are an easy way to iterate over results sets up to 10,000 items. This limit applies to the sum of values of parameters offset + rows.
The number of items returned in a single response is controlled by rows parameter (default is 20, and maximum is 1,000). To limit results to 5, for example, you could do the following:
/works?query=allen+renear&rows=5
offset parameter can be used to retrieve items starting from a specific index of the result list. For example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
/works?query=allen+renear&rows=5&offset=5
Deep paging using cursors can be used to iterate over large result sets, without any limits on their size.
To use deep paging make a query as normal, but include the cursor parameter with a value of *, for example:
/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 (remember to URL-encode). For example:
/members/311/works?filter=type:journal-article&cursor=<value of next-cursor parameter>
Clients should check the number of returned items. If the number of returned items is equal to 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.
Being able to select random results is useful for both testing and sampling. You can use the sample parameter to retrieve random results. So, for example, the following selects 10 random works:
/works?sample=10
Note that when you use the sample parameter, the rows and offset parameters are ignored.
Any combination of query, query.*, filter, facet, select and sort can be used with offsets. Sampling cannot be combined with offsets.
Any combination of query, query.*, filter, facet, select and sort may also be used with deep paging cursors. rows may also be specified.
offset and sample cannot be used in combination with cursors.
WorksMessage A list of works
ApiError
Optional cursor?: stringExposes the ability to deep page through large result sets, where offset would cause performance problems
Optional facet?: stringExposes the ability to retrieve counts for pre-defined facets e.g. type-name:* returns counts of all works by type
Optional filter?: stringExposes the ability to filter by certain fields, supports a comma separated list of lucene filters, e.g. content-domain:psychoceramics.labs.crossref.org
Optional mailto?: stringThe email address to identify yourself and be in the "polite pool"
Optional offset?: numberThe number of rows to skip before returning
Optional order?: stringCombined with sort can be used to specify the order of results, e.g. asc or desc
Optional query?: stringExposes the ability to free text query certain fields
Optional rows?: numberThe number of rows per page
Optional sample?: numberExposes the ability to return N randomly sampled items
Optional select?: stringExposes the ability to select certain fields, supports a comma separated list of fields, e.g. DOI,volume
Optional sort?: stringExposes the ability to sort results by a certain field, e.g. score
Gets the agency associated with a specific work by its DOI, as an example use DOI 10.5555/12345678
AgencyMessage The agency associated with work identified by {doi}.
ApiError
The DOI identifier associated with the work
Generated using TypeDoc
Returns metadata for the specified Crossref DOI, as an example use DOI 10.5555/12345678
Returns
WorkMessage The work identified by {doi}.
Throws
ApiError