Query schema
Queries to the XML API use XML format. The full schema can be found at https://data-crossref-org.turing.library.northwestern.edu/schemas/crossref_query_input2.0.xsd. This page provides an introduction and doesn’t cover all options available in the schema.
To make a query, we recommend the following workflow:
- Decide which fields to include in your query. This will depend on the information you have about the record or records you are looking for.
- Decide how to search. Some fields have options for how to query.
- Determine how many results to return and add other options.
Fields to include in your query
The following fields can be used in queries:
article_title, author, component_number, doi, edition_number, first_page, identifier, isbn, issn, issue, journal_title, name_choice, ORCID, proceedings_title, publication_type, series_title, standard_designator, unstructured_citation, volume, volume_title, year
To make a valid query:
- DOIs must follow the expected DOI format (10.XXXX/yyy…) and not exceed 200 characters.
- Either first page or author must be supplied.
- Either ISSN or journal title must be supplied.
- Either ISSN/ISBN or series/volume title must be supplied.
An invalid query will return no result, i.e. <body/>.
Query options
The match attribute for a field describes how the search is carried out. Depending on the field, it can have the following values:
fuzzy : Uses fuzzy matching rather than looking for an exact match.exact : Looks for an exact match to the value in the field. Cannot be combined with fuzzy or optional attributes.optional : This field may be dropped from the query.null : The value of this field must be null. Cannot be combined with other fields and no value should be provided.
match and its options are available for the following query fields:
| field | fuzzy | exact | optional | null |
|---|
article_title | x | x | | |
author | x | x | x | x |
component_number | x | x | | |
edition_number | x | x | | |
first_page | | x | x | x |
identifier | | x | x | |
institution_name | x | x | x | |
isbn | | x | x | |
issn | | x | x | |
issue | x | x | | |
journal_title | x | x | x | |
proceedings_title | x | x | x | |
publication_type | | | | |
series_title | x | x | x | x |
standard_designator | | | | |
standards_body_name | x | x | x | |
volume | x | x | x | |
volume_title | x | x | x | |
year | | x | x | |
It can’t be used for doi, ORCID, name_choice, or unstructured_citation.
Other search options
A query can have other attributes to determine how the search is conducted:
| Attribute | Possible values | Description |
|---|
key | Any string | Optional, for users to identify their query. |
enable-multiple-hits | true, false, multi_hit_per_rule, exact | Determines how many results to return, see below. |
forward-match | true, false | If true, stores the query and notifies you of new matches by email. |
list-components | true, false | If true, also returns records of type component. |
expanded-results | true, false | If true, returns additional author, article title, and date information. |
secondary-query | none, multiple-hits, author-title, author-title-multiple-hits | Perform a second type of query in case the first returns no results. See details below. |
To determine whether to return one or multiple results, you can use:
<query enable-multiple-hits:false> or <query secondary-query=none> are equivalent and return only one result. If multiple records match the query, no result will be returned.
<query enable-multiple-hits:true> or <query secondary-query=multiple-hits> have the same effect and will return any content items matching the query.
<query enable-multiple-hits:multi_hit_per_rule> treats each query field independently and returns all records that match any value in the query.
<query secondary-query:author-title> and <query secondary-query:author-title-multiple-hits> perform a query where only the title and first author are required, returning one or multiple records respectively. Providing additional fields overrides this option and a regular metadata query is performed.
