node-documentcloud
A Node.js wrapper around the DocumentCloud API. Requires Node.js >= 4
.
Installation
npm install --save documentcloud
Usage
The client interface makes it possible to pass in your DocumentCloud username and password so you can do authenticated requests. While this is not required for some endpoints, your experience will likely be much better if you are authenticated.
// import the library
var DocumentCloudClient = require('documentcloud');
// create a client
var client = new DocumentCloudClient('username', 'password');
// get to work!
client.documents.get('1659580-economic-analysis-of-the-south-pole-traverse', function (err, response) {
if (err) throw err;
console.log(response);
});
// {
// "status_code": 200,
// "response": {
// "document": {
// "id": "1659580-economic-analysis-of-the-south-pole-traverse",
// "title": "Economic Analysis of the South Pole Traverse",
// "access": "public",
// "pages": 38,
// ...
API Docs
DocumentCloudClient
The main DocumentCloud client. A DocumentCloud username and password are optional, but some methods are not available to unauthenticated users.
It is also possible to override the default base API URL.
Parameters
username
String= DocumentCloud username (optional, defaultnull
)password
String= DocumentCloud password (optional, defaultnull
)apiUrl
String= An override for the DocumentCloud API base URL. (optional, defaulthttps://www.documentcloud.org/api/
)
Examples
var DocumentCloudClient = require('documentcloud');
var client = new DocumentCloudClient('[email protected]', 'example_pw');
ProjectClient
Handles all methods that interact with project API endpoints.
Should never be created manually โ can be accessed on an instance of DocumentCloudClient
at DocumentCloudClient.projects
.
Parameters
client
Object Instance of DocumentCloudClient
create
Creates a project.
Parameters
title
String Title of project.opts
Object= Additional parameters to be included with project creationcallback
Function Callback to handle API response
delete
Deletes a project. Documents associated with the project are not effected.
Parameters
list
Lists all projects associated with the account.
Parameters
callback
Function Callback to handle API response
update
Updates data associated with a project. Do note - this replaces every field,
whether it is provided or not. For example - if you do not provide a list of document_ids
,
it will be set to none.
Parameters
project_id
Number The project identifieropts
Object Parameters to be set during the updatecallback
Function Callback to handle API response
DocumentClient
Handles all methods that interact with document API endpoints.
Should never be created manually โ can be accessed on an instance of DocumentCloudClient
at DocumentCloudClient.documents
.
Parameters
client
Object Instance of DocumentCloudClient
delete
Deletes a document on DocumentCloud.
Parameters
entities
Returns a list of entities associated with a document.
Parameters
get
Get a document's metadata from DocumentCloud.
Parameters
Examples
client.documents.get('1659580-economic-analysis-of-the-south-pole-traverse', function (err, response) {
if (err) throw err;
console.log(response);
});
// {
// "status_code": 200,
// "response": {
// "document": {
// "id": "1659580-economic-analysis-of-the-south-pole-traverse",
// "title": "Economic Analysis of the South Pole Traverse",
// "access": "public",
// "pages": 38,
// ...
search
Searches the DocumentCloud service for documents.
Parameters
q
String The search queryopts
Object= Additional search parametersopts.page
Number= Response page number (defaults to 1)opts.per_page
Number= The number of documents to return per page (defaults to 10, max is 1,000)opts.sections
Boolean= Include document sectionsopts.annotations
Boolean= Include document annotationsopts.data
Boolean= Include key/value data in resultsopts.mentions
Number= Include highlighted mentions of search phrase (none by default, max is 10)opts.order
String= Order documents are listed (defaults tocreated_at
, choices are:score
,created_at
,title
,page_count
,source
)
callback
Function Callback that handles the API response
update
Update a document's title, source, description, related article, access
level, or data values. Values passed into opts
will be updated on the
requested document.
Parameters
doc_id
String Document identifieropts
Object Values to updateopts.title
String= Title of documentopts.source
String= Source of documentopts.description
String= Description of documentopts.related_article
String= URL of article associated with documentopts.published_url
String= URL of page where document will be embeddedopts.access
String= Sets access level (defaults toprivate
, choices are:private
,public
,organization
) (optional, defaultprivate
)opts.data
Object= Object of key/value pairs to associate with document
callback
Function Callback that handles the API response
upload
Uploads a document to DocumentCloud.
The file
can be a path to a document on disk, a Node.js Buffer, or the
URL to a public file.
Parameters
file
(String|Buffer) Path to a file, a Node.js Buffer, or public URLtitle
String Title of uploaded documentopts
Object= Additional parameters to be included with uploadopts.source
String= Source of documentopts.description
String= Description of documentopts.language
String= Language of document, will be used determine which OCR package to be used (optional, defaulteng
)opts.related_article
String= URL of article associated with documentopts.access
String= Sets access level (defaults toprivate
, choices are:private
,public
,organization
) (optional, defaultprivate
)opts.project
Number= Numeric ID of project to add document toopts.data
Object= Object of key/value pairs to associate with documentopts.secure
Boolean= If the document is sensitive, settingsecure
totrue
will prevent it from being sent to OpenCalais for entity extractionopts.force_ocr
Boolean= Forces a document to OCR'd even if it has textopts.published_url
String= URL of page where document will be embedded
callback
Function Callback that handles the API response
Major Thanks
- Thanks to DocumentCloud for creating and maintaining such an awesome service.
- Thanks to python-documentcloud, who served as inspiration for many parts of this.