DEVELOPER DOCUMENTATION Home API Documentation RIS Import Cite Widget

Citation API Documentation

Note: If you are a service looking to import RIS data, please refer to our RIS import documentation.

1. Introduction

1.0 Overview

The EasyBib Citations API is a way for third parties to create accurate, fully-formatted bibliographical citations. It is a REST-based API that works by receiving raw source data and responding with a formatted citation. A full list of sources and options is available in Appendix A.

Some use cases for this API include:

  • Electronic databases utilizing the API to create exportable citations for their content
  • Online newspapers and scientific journals using the API to create citations for their articles
  • Blogs adding citations for their posts to encourage readers to cite them in their own works
  • Research applications using the Citations API to generate citations for later retrieval

As with any API, there are some rules of the road. We're a pretty flexible with how you use the API, but set the following terms:

  • To utilize the API, you need an authentication key that we tie to an IP. Abuse of our service will result in a revocation of your key.
  • Commercial usage of the API may be subject to fees. Please contact us for more details.

1.1 A Basic Example

Say you are a book publisher and want to display a citation of the books you sell on each of your Web pages. You can do this very easily with the Citations API.

First, send us a JSON-encoded request structured like below.

{
"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"
}
]
}
We'll respond with the following JSON-encoded string that you can pick up.

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

And that's basically it! If you want to receive a citation in two styles, just send two JSON requests.




2.0 The Full API Details

2.1 Basic structure

Every request must include the following information:

  • key: your authentication key if required. Formatting data for your own use requires a key (2.3.1), whereas sending data to EasyBib does not (2.3.2). For more information about authentication, see 2.4.
  • source: type of source, like book, magazine, journal (see Appendix A)
  • style: one of the following three options: mla7, apa, chicagob (see Appendix A)

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
}
]
}

2.2 A brief overview of JSON


Most programming and scripting languages have a direct interface to convert an array/object to JSON.


For example (PHP): (other examples here)


<?php
$test = array('test', 'hello', 'world');

echo json_encode($test); // ["test","hello","world"]
?>


In case you have no access to such features, please visit the following link to verify that the JSON you are creating is valid:
http://www.jsonlint.com/ 


2.3 Requests, method and structure


2.3.1 Option 1: Get a fully formatted citation for your own use


This option returns a fully formatted citation. You can then use this citation to display on your site. For instance, if you are an electronic database publisher, you can use EasyBib to automatically generate citations to display back to the user.  To go this route, send the JSON data to the following URL via PUT:


     http://api.easybib.com/2.0/rest/cite



2.3.1.1 Sending responses via PUT

Most scripting and programming languages allow you to create an http request object, which you then use to take the JSON data and send it to us via PUT. We have outlined some example code snippets in Appendix 3. If you do not see your language of choice in this section, and are confused about how to do this, contact us and we'll help you.

2.3.1.2 The response

The returned data ("response") from EasyBib always includes a "status" field. Possible values are:

  • ok
  • error

These values will always be lowercase, and English.  An example successful request is above - here it is again:

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

In case of "error", the response will also populate a field called "message", which contains a description of the error which has occurred. This error is most likely not suitable for the end user and should be treated/escalated internally. For example:

    {
        "status":"error",
        "message":"Missing required field 'style' in request."

    }


A list of all possible error messages are in Appendix B.


Once you get this JSON object, you can then decode it and use the data to present a citation back to your user.


2.3.2 Option 2: Populate EasyBib form fields with citation data


Another option we provide is letting third parties automatically post data to EasyBib. This option provides a seamless way for content providers to let their users save citations directly to their EasyBib account. This is similar to offering an "export to bibliography manager," but since EasyBib is online and free, can be a more useable option for users.


To go down this route, just POST the JSON data, named "data", to EasyBib. You may want to URL-encode it to prevent things like quotations breaking your form submission.


For instance: <input type="hidden" name="data" value="[your url-encoded json data]" />


The URL to post to is:


http://www.easybib.com/cite/form


Your data will then appear in the appropriate EasyBib forms based on the source field you included.


2.3.2.1 Bulk posting citation data


For services wishing to allow their users the ability to save multiple citations to EasyBib at one time, we offer a method of sending data in bulk.


The payload should be structured as a json array, with each citation as a json string, and given a POST name of 'data':


POST 'data': [{json_string1}, {json_string2}]


and sent to http://www.easybib.com/cite/bulk


Note: This URI supports posting of a maximum of 20 citations at a time.


2.4 Authentication


Option 2.3.1 requires an API key. Sign up here to get an API key automatically.

Option 2.3.2 does not require an API key.




APPENDIX A: 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 Appendix D.


A.2 Style options (Required)

Style Description


mla7  Modern Language Association - 7th edition
apa American Psychological Association - commonly used in the sciences
chicagob Chicago (Turabian) Notes-Bibliography system - commonly used in humanities


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: storyessay
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 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: authoreditorcompilertranslator
  • chapter source only: section_authorsection_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
book 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",  (day of creation)
"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", (page start and page end)
"end":"100",
"nonconsecutive":"0" (1 if pages are non-consecutive)
}
,
"contributors":
[
{
"function":"author",
"first":"Firstname",
"middle":"Middlename",
"last":"Lastname"
}
]
}






A.8 API v.2.1 releases (custom_id, section_id)

The API URL should be http://api.easybib.com/2.1/rest/cite or http://api.easybib.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"
}





APPENDIX B: Error codes

//todo




APPENDIX C: PUT request objects in different languages

Below are a few ways to create http request objects that can be used to send PUT data to EasyBib.

PHP (Zend Framework):
        
        $citation_data = Zend_Json::encode($results);
        
        //create http client

        $url    = 'http://api.easybib.com/2.0/rest/cite';
        $client = new Zend_Http_Client($url);

        $resp = $client->setRawData($citation_data, 'application/json')
                ->request('PUT')
                ->getLastResponse()
                ->getBody();
        
        $citation = Zend_Json::decode($resp);
        
        if ($citation['status'] == 'ok') {
            $formatted_citation = $citation['data'];
        } else {
            $error_message = $citation['message'];
              }


ASP / VB .NET:

'Creating a JSON object:

Dim yourData As String() = { "Hello", "World" }
Dim jsonSerialiser As New System.Web.Script.Serialization.JavaScriptSerializer
Dim jsonString as String = jsonSerialiser.Serialize(yourData)

'Set Up Needed Objects
Dim easyBibRequest As HttpWebRequest
Dim easyBibResponse As HttpWebResponse
Dim easyBibStream As System.IO.Stream
Dim data As String
Dim encoding As New System.Text.ASCIIEncoding()
Dim arr() As Byte
'Retrieve The Data To Send To EasyBib and Convert To A Byte Array
data = jsonString 'JSON STRING
arr = encoding.GetBytes(data)
'Create and Set Up Request
easyBibRequest =
CType(HttpWebRequest.Create("http://api.easybib.com/rest/cite"), HttpWebRequest)
easyBibRequest.Method =
"PUT"
easyBibRequest.ContentLength = arr.Length
easyBibRequest.KeepAlive =
True

'Get Request Stream and Write Data We Want To Send To It
easyBibStream = easyBibRequest.GetRequestStream()
easyBibStream.Write(arr, 0, arr.Length)

'Get the Response and Read From It
easyBibResponse =
CType(easyBibRequest.GetResponse(), HttpWebResponse)
easyBibStream = easyBibResponse.GetResponseStream()

Dim easyBibReader As New System.IO.StreamReader(easyBibStream, System.Text.Encoding.UTF8)

'Finally, Write to the Response The Data We Got Back From EasyBib
Response.Write(easyBibReader.ReadToEnd())


If you do not see your language here, first see if you can do a quick Google search ([language] http put request).  There should be enough code out there to help you. You can also contact us.




APPENDIX D



APPENDIX E

Additional informational fields

These fields are currently unused in citation format, however, we can store them.
  • "issn":"issn number"
  • "keywords":{"kw1", "kw2" ... }
  • "abstract":"abstract text"
  • "doi":{"doi":"doi number goes here.."}
  • "datasource":"[datasource]"
  • "oclc":"oclc number"

APPENDIX F

Case studies

Example 1: Organization has a lot of book listings available, and it wants to allow users of its site to cite books. It decides to add an "export to EasyBib" button to its different books.

To implement this feature, they can create a <form> next to e
ach one of their books that contains the citation data, formatted for EasyBib export.

1. The first step is to create the JSON citation string. It looks like this:

{
"source":"book",
"pubtype":{"main":"pubnonperiodical"},
"pubnonperiodical":
{
"title":"The Catcher in the Rye",
"publisher":"Little, Brown",
"city":"Boston",
"year":"1951"
}
,
"contributors":
[
{
"function":"author",
"first":"Jerome",
"middle":"David",
"last":"Salinger"
}
]
}

Note: Green text is for values that can be, but should not be, changed if you have the exact needs of this case study. The blue values should be changed to match the specific data of your source.

2. The next step is to URL encode the string, and put it into a hidden field named 'data'. At the end, the full form looks like this:

<form method="POST" action="http://www.easybib.com/cite/form">
  <input type="hidden" name="data" value="%7B%22source%22%3A%22book%22%2C%22pubtype%22%3A%7B%22main%22%3A%22pubnonperiodical%22
%7D%2C%22pubnonperiodical%22%3A%7B%22title%22%3A%22The+Catcher+in+the+Rye%22%2C%22publisher%22
%3A%22Little%2C+Brown%22%2C%22city%22%3A%22Boston%22%2C%22year%22%3A%221951%22%7D%2C
%22contributors%22%3A%5B%7B%22function%22%3A%22author%22%2C%22first%22%3A%22Jerome%22
%2C%22middle%22%3A%22David%22%2C%22last%22%3A%22Salinger%22%7D%5D%7D" />
  <input type="submit" value="Cite on EasyBib!" />
</form>


Example 2: An electronic database has a number of journal articles that subscribers access. It wants to add citation capabilities to its site, so decides to add an "Export to EasyBib" button. They want to make sure their database information also is appended to the citation.

{
"source":"journal",
"journal":
{
      "title":"Industry structure, market rivalry, and public policy"
}
,
"pubtype":{"main":"pubjournal", "suffix":"pubdatabase"},
"pubjournal":
{
"title":"Journal of Law and Economics",
"volume":"16",
"issue":"1",
"year":"1973",
"start":"1",
"end":"9"
}
,
"contributors":
[
{
"function":"author",
"first":"Harold",
"last":"Demsetz"
}
]
,
"pubdatabase":
{
     "service":"Company name",
     "db":"Specific database name",
     "searchtext":"http://www.url.com/article?id=321424",
     "day":"3",
     "month":"march",
     "year":"2002",
     "dayaccessed":"10",
     "monthaccessed":"april",
     "yearaccessed":"2010"
}
}

Note: Green text is for values that can be, but should not be, changed if you have the exact needs of this case study. The blue values should be changed to match the specific data of your source.

2. The next step is to URL encode the string, and put it into a hidden field named 'data'. At the end, the full form looks like this:

<form method="POST" action="http://www.easybib.com/cite/form">
  <input type="hidden" name="data" value="%7B%22source%22%3A%22journal%22%2C%22journal%22%3A%7B%22title%22%3A%22
Industry+structure%2C+market+rivalry%2C+and+public+policy%22%7D%2C%22pubtype%22
%3A%7B%22main%22%3A%22pubjournal%22%2C+%22suffix%22%3A%22pubdatabase%22%7D%2C%22
pubjournal%22%3A%7B%22title%22%3A%22Journal+of+Law+and+Economics%22%2C%22volume%22
%3A%2216%22%2C%22issue%22%3A%221%22%2C%22year%22%3A%221973%22%2C%22start%22%3A%221%22
%2C%22end%22%3A%229%22%7D%2C%22contributors%22%3A%5B%7B%22function%22%3A%22author%22
%2C%22first%22%3A%22Harold%22%2C%22last%22%3A%22Demsetz%22%7D%5D%2C%22pubdatabase%22
%3A%7B%22service%22%3A%22Company+name%22%2C+%22db%22%3A%22Specific+database+name%22
%2C%22searchtext%22%3A%22http%3A%2F%2Fwww.url.com%2Farticle%3Fid%3D321424%22%2C%22
day%22%3A%223%22%2C%22month%22%3A%22march%22%2C%22year%22%3A%222002%22%2C%22
dayaccessed%22%3A%2210%22%2C%22monthaccessed%22%3A%22april%22%2C%22yearaccessed%22
%3A%222010%22%7D%7D" />
  <input type="submit" value="Cite on EasyBib!" />
</form>

To implement this feature, they can create a <form> next to e
ach one of their journal articles that contains the citation data, formatted for EasyBib export.


APPENDIX G

Analytics

Due to the JSON schema of the Citation API, it can be difficult to easily determine answers to questions like "What field do I use to find the title of a source." Here are some tips:

Titles:

  • If the article title exists, e.g. data.source.title, use that. Otherwise, use the publication title: data[data.pubtype.main].title
  • Article titles are the name of the article, whereas a publication title is the title of the source containing the article. For example, "U.S. Trains Commandos in Fight Against Terrorism" is an article title, and the source title is New York Times.
  • Use article title when it exists and is not empty, and publication title otherwise.
  • Example:
    • source: newspaper
    • pubtype.main: pubnewspaper
    • Use data.newspaper.title or if this does not exist, data.pubnewspaper.title is what you should use.
Authors:
  • data.contributors
  • Example:
    • {"contributors" : ...}
URL:

  • Use data.pubonline.url if it exists, or use data.pubdatabase.searchtext if it exists.
  • Example:
    • data.pubonline.url = url of source, or data.pubdatabase.searchtext = url of source
Publisher:
  • data[data.pubtype.main].publisher
Date published:
  • data[data.pubtype.main].day
  • data[data.pubtype.main].month
  • data[data.pubtype.main].year
  • Example:
    • For example, let's say data.pubtype.main = pubjournal
    • data.pubjournal.day, data.pubjournal.month, and data.pubjournal.year are what you should be using.