Citoid/API

This document describes how to interact with the native API for the citoid service. However, in production we are running citoid behind restbase, which uses a different request format, for which the documentation can be found at https://en.wikipedia.org/api/rest_v1/#!/Citation/getCitation. Only the response section in this documentation is relevant for restbase requests.

Locally a version of this documentation can be found at http://localhost:1970/?doc.

Requests

The API endpoint accepts GET data. In the GET request, three arguments are accepted: search and format.

Arguments

search currently takes URLs, DOIs, PMCIDs, and PMID, ISBNs, QIDs, and fully formatted citations / free text search. If the unique identifier is unresolvable, you will get back a 404 response and a JSON error message.

format takes 'mediawiki', 'zotero' , 'bibtex' , and 'mediawiki-basefields'. 'zotero'is the format used by the zotero service, and is the format that citoid uses internally. 'mediawiki' is the targeted format, and is designed for use by TemplateData maps found in citation templates. You may find, depending on your use case, for the 'zotero' format to be richer. The format 'mediawiki-basefields' is largely the same as 'mediawiki' , but will return the base fields for the data in instead of the mapped fields. For example, it will return publicationTitle instead of bookTitle or websiteTitle.

Headers

To try to request a website in a particular language, you can set the accept-language header in your request, and citoid will attempt to retrieve the website in that language.

This will not work if the website does not use the accept-request header in order to determine what language to return the sites in or if the requested language isn't available (which is often.)

Response

Successful response in mediawiki format

A successful (200 ok) citoid response for the 'mediawiki' format consists of an Array of citation Objects, [{}] in the body. At present, there will be only one citation Object in the Array if you do not have a WorldCat key / if the wskey option is turned off. If you have enabled WorldCat requests and have a wskey (this is the case in production), then you can receive up to 2 results with a free text search only. These results consist of the top result from crossref simple text query (journal articles and other resources with a doi) and the top result from WorldCat OpenSearch (books and other resources with an ISBN) if you have enabled it. Requests for a URL or other unique identifier will return only one result.

Field names

The 'mediawiki' format uses the same itemTypes and parameter names as the 'zotero' format, with four additional parameters: PMID, PMCID,oclc , and source. A nearly complete list of all itemTypes possible and each itemType's respective parameters are available from Zotero here.

Parameters for which there is no value will not be included in the response. There are three required parameters that will always be returned: itemType , url and title (or one of its corresponding type-specific parameters: caseName, subject or nameOfAct).

Parameters which are written in parentheses on the Zotero type map are called basefields. By default, you will get the first parameter name. You can request the basefield instead as a query parameter in the request.

Field values

The values for most fields are Strings. The value of the fields issn , isbn, and source are Arrays of Strings. The value of any creator type (i.e. author, editor, programmer, etc.) is an Arrays of Arrays, i.e. [['firstname'],['lastname']].

The possible String values in the Array source are: 'citoid', 'Crossref', 'PubMed', and 'Zotero'. This indicates where the metadata was retrieved from.

Unsuccessful response

Alongside regular errors (400 Bad Request), we have a custom 520 response that returns a citation object even if no data is able to be retrieved.

Examples

Making a request to API/ endpoint (GET)

In a browser

http://localhost:1970/api?search=10.1038%2Fng.590&format=mediawiki

In a JavaScript userscript

$.ajax( {
	beforeSend: function (request) {
		request.setRequestHeader('Content-Type', 'application/json');
		request.setRequestHeader('accept-language', 'en'); // Use this header to request the resource in the particular language, i.e. 'en', 'de'

	},
	url: ' https://citoid.wikimedia.org/api',
	type: 'GET',
	data: { 
		search: encodeURIComponent('10.1038/ng.590'),
		format: 'mwDeprecated'
	},
	dataType: 'json',
	success: function ( citationArray ) {
		doSomething( citationArray );
	},
	error: function ( request, textStatus, errorThrown) {
		alert( 'Status:'  + textStatus +  'Error: ' + errorThrown );
	}
} );

Sample output

Below are sample outputs of two of the export formats. The primary difference is in how creators/authors/editors are handled. In zotero, these are all in the creator object, and in mediawiki they are in a list of [firstname, lastname] lists keyed by the creatorType value. In only mediawiki, ISBN and ISSN are lists.

zotero

[ { "DOI" : "10.1371/journal.pcbi.1002947",
      "ISSN" : "1553-7358",
      "abstractNote" : "Viral phylodynamics is defined as...",
      "creators" : [ { "creatorType" : "author",
            "firstName" : "Erik M.",
            "lastName" : "Volz"
          },
          { "creatorType" : "author",
            "firstName" : "Katia",
            "lastName" : "Koelle"
          },
          { "creatorType" : "author",
            "firstName" : "Trevor",
            "lastName" : "Bedford"
          }
        ],
      "date" : "2013",
      "extra" : "PMID: 23555203 \nPMCID: PMC3605911",
      "issue" : "3",
      "itemKey" : "XK9ACBRA",
      "itemType" : "journalArticle",
      "itemVersion" : 0,
      "journalAbbreviation" : "PLoS Comput. Biol.",
      "language" : "eng",
      "libraryCatalog" : "NCBI PubMed",
      "pages" : "e1002947",
      "publicationTitle" : "PLoS computational biology",
      "tags" : [ { "tag" : "Adaptation, Biological",
            "type" : 1
          },
          { "tag" : "Computational Biology",
            "type" : 1
          }
        ],
      "title" : "Viral phylodynamics",
      "volume" : "9"
    } ]

mediawiki

[ { "DOI" : "10.1371/journal.pcbi.1002947",
    "ISSN" : ["1553-7358"],
    "PMID" : "23555203",
    "abstractNote" : "Viral phylodynamics is defined as...",
    "author" : [ [ "Erik M.",
          "Volz"
        ],
        [ "Katia",
          "Koelle"
        ],
        [ "Trevor",
          "Bedford"
        ]
      ],
    "date" : "2013",
    "extra" : "PMID: 23555203 \nPMCID: PMC3605911",
    "issue" : "3",
    "itemKey" : "CTVVXDEA",
    "itemType" : "journalArticle",
    "itemVersion" : 0,
    "journalAbbreviation" : "PLoS Comput. Biol.",
    "language" : "en",
    "libraryCatalog" : "NCBI PubMed",
    "pages" : "e1002947",
    "publicationTitle" : "PLoS computational biology",
    "tags" : [ { "tag" : "Adaptation, Biological",
          "type" : 1
        },
        { "tag" : "Computational Biology",
          "type" : 1
        }
      ],
    "title" : "Viral phylodynamics",
    "url" : "http://www.ncbi.nlm.nih.gov/pubmed/23555203",
    "volume" : "9",
    "source" : ["Zotero"]
  } ]