Citation Formatting Api – Api Spec v2.1

This specifies the EasyBib Formatting API Version 2.1. There are two different ways to handle citations using our API:

  1. Get a fully formatted citation for your own use (Documentation)
  2. “Export to EasyBib”: Populate EasyBib form fields with citation data (Documentation)

Retrieving a formatted citation requires an API key – please sign up here first. Sending to EasyBib does not require a key.

Basic structure

Every request must include the following information:

  • key: your authentication key if required. Formatting data for your own use requires a key, whereas sending data to EasyBib does not.
  • source: type of source, like book, magazine, journal; (see Appendix A)
  • style: one of the following options: mla7, apa, chicagob, (our most popular) or other styles

Beyond that, the citation data must be stored in one of three sections

  • [source] (array): citation data that is specific to this source type
  • [pubtype] (array): citation data that is related to the publication of the source
  • contributors (arrays within an array): citation data that is related to the contributors of the source (authors, editors, etc.). Each contributor is its own array, and there can be multiple contributors listed within the contributors section.

Therefore, the raw basic structure you would be sending to EasyBib would look like the following:

{
    "key": "[your api key]",
    "source": "[source name]",
    "style": "[style]",
    "[source]": {
    },
    "pubtype": {
        "main": "[pub type]",
        "suffix": "[suffix type, if any]"
    },
    "[pub type]": {
        //publication data
    },
    "contributors": [
        {
            //contributor 1
        },
        {
            //contributor 2
        }
    ]
}

Npnd Parameter

You can supply an optional parameter npnd to control the output of “n.p.” and “n.d.” in the formatted citation – valid values are yes and no, if defaults to yes. Example:

{
    "key": "[your api key]",
    "source": "[source name]",
    "style": "[style]",
    "npnd": "no",
    //additional source metadata
}

What does n.p and n.d. mean?

In some styles, notably MLA 7th edition and APA, you may see the acronyms “n.p.” or “n.d.” in your citation.
N.p. stands for “No place” or “no publisher”, and shows up when no publication city or publisher has been given for that medium of publication.
N.d. stands for “No date” and shows up when no publication date has been provided for that medium of publication.

Additional metadata

The API supports and stores additional metadata fields – they usually are not used to format a citation (except DOI depending on the style), but are stored in the API if provided. See section A8 in the Formatting API specification for an example.

  • “issn”:”issn number”
  • “keywords”:{“kw1”, “kw2” … }
  • “abstract”:”abstract text”
  • “doi”:{“doi”:”doi number goes here..”}
  • “datasource”:”[datasource]”
  • “oclc”:”oclc number”
  • “custom_id”:”api-user identifier”
  • “section_id”:”page/section identifier”

Footnotes

The chicagob citation style supports footnotes. To use this, you must consider two two things:
– A type field in the first level of hierarchy of the citation JSON. The value for this needs to be “footnotes”.
– In the response for the citation, you’ll see |PAGE|. This is the delimiter you must replace with the page number the user wants to cite.

Example:

$data = '{
    "key": "[YOUR CODE HERE]",
    "source": "book",
    "type":"footnotes",
    "style": "chicagob",
    "book": {},
    "pubtype": {
        "main": "pubnonperiodical"
    },
    "pubnonperiodical": {
        "title": "Catcher in the Rye",
        "publisher": "Little, Brown",
        "city": "Boston",
        "year": "1995",
        "start": "Starting page number"
    },
    "contributors": [
        {
            "function": "author",
            "first": "J",
            "middle": "D",
            "last": "Salinger"
        }
    ]
}';

The response should look as follows:

{"status":"ok","data":"J. D. Salinger, <i>Catcher in the Rye<\/i> (Boston: Little, Brown, 1995), |PAGE|."}

(Note: you must replace |PAGE| after the response comes back with the appropriate page number.