Citation Object Specification

Full Citation Specification

To clarify what data elements each of the tables references, we’ve laid out the skeleton JSON string below, mapping it to the appropriate section.

{
    "key":"[your api key]",    // You should obtain an API key from us
    "source":"[source name]",  // Section A.1
    "style":"[style]",         // Section A.2
    "[source name]": {
        // Section A.3
    }
    "pubtype": {
        "main":"[pub type]",
        "suffix":"[pub suffix type]"},
        "[pub type]": {
            // Section A.4
        },
        "contributors": [
            // Section A.5
        ],
        "[pub suffix type]": {
            // Section A.6 (optional!)
        }
    }
}

A.1 Source types (Required)

Source type Description
book A book (Catcher in the Rye, Harry Potter, etc.)
chapter A section of a book or a story in an anthology
magazine A magazine (Time, The New Yorker, etc.)
newspaper A newspaper (New York Times, Washington Post, etc.)
journal A scholarly journal (Journal of Literary Studies, American Political Science Review, etc.)
website A web page article (About.com, Wikipedia, etc.)

There are way more source types you can choose from (above are the six main ones). To view those, please see our full specification for the citation object..

A.2 Style options (Required)

  • Get popular styles: http://api.citation-api.com/2.1/rest/popular-styles
    • returns {"status":"ok","data":{"mla7":"MLA","apa":"APA","chicagob":"Chicago\/Turabian"}}
    • jsonp: http://api.citation-api.com/2.1/rest/popular-styles?callback=easybib
  • Get other styles: EasyBib supports over 6000 other citation styles. To view a full list, please use the list found here: http://api.citation-api.com/2.1/rest/styles. This url supports pagination and search as well – use the GET parameters `query` for a string-search, and `page` for pagination.

We recommend you cache this list in the application you use. To peruse this list, we recommend installing a plugin that helps you read JSON more easily, such as JSONview

A.3 Source arrays

Source data should be formatted in the following way (examples only):

"[source name]": {
    "title":"Journal article title"
}

book
No source_data options. Keep source_data blank (empty brackets).

chapter

type two options: story, essay
title name of chapter / story title

magazine

title article title

newspaper

title article title

journal

title article title

website

title web page title

A.4 Publication arrays

Each source type has a related publication type:

A.4.1 Source – Publication mapping

Source type Publication options
book pubnonperiodical
chapter pubnonperiodical
magazine pubmagazine
newspaper pubnewspaper
journal pubjournal
website pubonline

Example publication section:

    "[pub type]": {
        "title": "Catcher in the Rye",
        "publisher": "Little, Brown",
        "city": "Boston",
        "year": "1983"
    }

pubnonperiodical

title Book title
publisher Publisher name
city City published
state State published
vol Volume
editiontext Edition
year Year published (four digits: ie 2000)
start Start page (for chapter sources)
end End page (for chapter sources)

pubmagazine

title Magazine title
vol Magazine volume
day Day published (1-31)
month Month published (full month names: January through December)
year Year published (four digits: ie. 2000)
start Start page of article
end End page of article
nonconsecutive 1 if article is on nonconsecutive pages, blank or 0 if not

pubnewspaper

title Newspaper title
edition Newspaper edition (late, etc.)
section Newspaper section
city City published
day Day published (1-31)
month Month published (full month names: January through December)
year Year published (four digits: ie. 2000)
start Start page of article
end End page of article
nonconsecutive 1 if article is on nonconsecutive pages, blank if not

pubjournal

title Journal title
issue Journal issue number
volume Journal volume number
restarts Do journal issues restart their page numbering? If yes, use 1, if no, leave blank.
series Journal series
year Year published (four digits: ie. 2000)
start Start page of article
end End page of article
nonconsecutive 1 if article is on nonconsecutive pages, blank if not

pubonline

title Web site title
inst Institution associated with
day Day published (1-31)
month Month published (full month names: January through December)
year Year published (four digits: ie. 2000)
url URL of Web site (ie. http://www.google.com)
dayaccessed Day Web page was accessed
monthaccessed Month Web page was accessed
yearaccessed Year Web page was accessed

A.5 Contributor arrays

A source can have multiple contributors, and each contributor has multiple fields. Therefore, when creating the JSON object, please make sure the individual contributors are embedded as an array within the main contributor array. For example:

One contributor:

    "contributors": [
        {
            "function": "author",
            "first": "J",
            "middle": "D",
            "last": "Salinger"
        }
    ]

Two contributors:

    "contributors": [
        {
            "function": "author",
            "first": "J",
            "middle": "D",
            "last": "Salinger"
        },
        {
            "function": "editor",
            "first": "John",
            "last": "Doe"
        }
    ]
Contributor field Description
function Options include:

  • all sources: author, editor, compiler, translator
  • chapter source only: section_author, section_editor (relates to contributors for specific chapter; other contributors can also be used)
first first name
middle middle name / initial
last last name

A.6 suffix publication table

We built the suffix publication element to account for sources that were originally published in one medium, and then found in another.  For instance, if a magazine article is published originally in print, but then found through an electronic database, the suffix publication for pubdatabase would be used.

Example suffix section:

    "[suffix pub type]": {
        "day": "3",
        "month": "May",
        "year": "2007",
        "url": "http://www.about.com"
    }

Below is a table of the different suffix publication options each of the sources has.

A.6.1 Source – Suffix publication mapping

Source type Suffix options
ook pubonline, pubdatabase
chapter pubonline, pubdatabase
magazine pubonline, pubdatabase
newspaper pubonline, pubdatabase
journal pubonline, pubdatabase
website none

pubonline
See Section A.4

pubdatabase

service Service name (ex. )
db Database name
day Day published (1-31)
month Month published (full month names: January through December)
year Year published (four digits: ie. 2000)
searchtext URL for the database (ex. http://www.proquest.com)
dayaccessed Day database was accessed
monthaccessed Month database was accessed
yearaccessed Year database was accessed

A.7 Example data structures for popular source types

Books

{
    "key": "[your api key]",
    "source": "book",
    "style": "mla7",
    "book": {
    },
    "pubtype": {
        "main": "pubnonperiodical"
    },
    "pubnonperiodical": {
        "title": "Catcher in the Rye",
        "publisher": "Little, Brown",
        "city": "Boston",
        "year": "1995"
    },
    "contributors": [
        {
            "function": "author",
            "first": "J",
            "middle": "D",
            "last": "Salinger"
        }
    ]
}

Websites

{
    "key": "[your api key]",
    "source": "website",
    "style": "mla7",
    "website": {
        "title": "Specific Webpage article title"
    },
    "pubtype": {
        "main": "pubonline"
    },
    "pubonline": {
        "title": "Title of entire website",
        "inst": "Organization that owns web site",
        "day": "6", 
        "month": "january",
        "year": "2001",
        "dayaccessed": "9",
        "monthaccessed": "may",
        "yearaccessed": "2012"
    },
    "contributors": [
        {
            "function": "author",
            "first": "Firstname",
            "middle": "Middlename",
            "last": "Lastname"
        }
    ]
}

Journal

{
    "key": "[your api key]",
    "source": "journal",
    "style": "mla7",
    "journal": {
        "title": "Specific journal article title"
    },
    "pubtype": {
        "main": "pubjournal"
    },
    "pubjournal": {
        "title": "Title of journal",
        "vol": "volume number",
        "issue": "issue number",
        "series": "series description",
        "year": "2001",
        "start": "89",
        "end": "100",
        "nonconsecutive": "0"
    },
    "contributors": [
        {
            "function": "author",
            "first": "Firstname",
            "middle": "Middlename",
            "last": "Lastname"
        }
    ]
}

Note:start/end indicate the respective first and last page. nonconsecutive should be set to ‘1’ if the pages are non-consecutive.

A.8 Additional Metadata fields

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.

  • “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 (see below)”
  • “section_id”:”page/section identifier (see below)”

The API URL should be https://api.citation-api.com/2.1/rest/cite or https://api.citation-api.com/2.0/rest/bulk.

custom_id: Some users may require attaching a custom identifier to their citation data to track back their API requests. To do that, attach a custom_id field with the necessary identifier and we will transparently pass this back in the response.

section_id: When formatting footnotes, you can include this field at the top level to specify the specific page/section you want to cite.

Data request:

{
    "key": "[your api key]",
    "custom_id": "CUSTOMID",
    "source": "book",
    "style": "chicagob",
    "type": "footnotes",
    "section_id": "34",
    "book": {
    },
    "pubtype": {
        "main": "pubnonperiodical"
    },
    "pubnonperiodical": {
        "title": "Catcher in the Rye",
        "publisher": "Little, Brown",
        "city": "Boston",
        "year": "1995"
    },
    "contributors": [
        {
            "function": "author",
            "first": "J",
            "middle": "D",
            "last": "Salinger"
        }
    ]
}

Response:

{
    "status": "ok",
    "data": "...citation here, including section_id...",
    "custom_id": "CUSTOMID"
}