Follow us on Facebook to receive important updates Follow us on Twitter to receive important updates Follow us on sina.com's microblogging site to receive important updates Follow us on Douban to receive important updates
Chinese Text Project

CTP API

The Chinese Text Project Application Programming Interface (CTP API) provides methods for integrating content and functionality of the CTP with other web-based or web-aware sites and applications. The API consists of two main components: a plugin API which integrates external functionality into the CTP, and a JSON API which allows CTP functionality to be integrated into external sites.

This page contains technical documentation for those interested in creating their own plugins. If you would like to learn how to use existing plugins from a user perspective, you may wish to read the Plugins page first.

Plugin API

The plugin API defines functional link points within the CTP, allowing these to be connected to external websites and user-defined tools. Users can then choose to install these plugins without requiring technical knowledge. Some examples of existing plugins are shown below.

PluginDescriptionTypeExampleInstall
Text toolsTools for textual analysis.chapter, book [Text tools] [Install]
AnnotateTools for textual annotation.chapter [Annotate] [Install]
Text tools (beta version)Tools for textual analysis (beta version).chapter, book [Text tools (beta version)] [Install]
Plain textExport as plain text.book, chapter [Plain text] [Install]
TextRefList editions of a title on TextRef.org.book [TextRef] [Install]
MHDBMHDB character lookup.character, word [MHDB] [Install]

[More...]

Technically, a plugin is a description in XML of a programmatic way of linking to an external resource. Plugins must be valid XML conforming to the CTPPlugin DTD. An example plugin XML file is as follows: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE CTPPlugin PUBLIC "CTPPlugin" "http://ctext.org/plugins/ctpplugin.dtd">
<CTPPlugin xmlns="http://schema.ctext.org/Plugin">
<Plugin>
  <ShortName xml:lang="en">Plain text</ShortName>
  <ShortName xml:lang="zh">全文輸出</ShortName>
  <Description xml:lang="en">Export a chapter as plain text.</Description>
  <Description xml:lang="zh">輸出原典全文。</Description>
  <Url template="https://ctext.org/plugins/textexport/#{textRef}" pluginType="chapter" fieldEncoding="utf8" method="get" />
  <Update src="https://ctext.org/plugins/textexport/plugin.xml" />
</Plugin>
</CTPPlugin>
The XML source of the current version of this plugin can be downloaded from the specified update URL.

To create your own plugin, start with this template and modify the appropriate elements as follows:

If you wish to provide different names and descriptions for English and Chinese users, the elements ShortName and Description can be repeated with xml:lang set to "en" for English, and "zh" for Chinese as shown in the above example.

URL schemas

The "template" element of a plugin must contain the "src" attribute, specifying a URL schema allowing the CTP to programmatically generate appropriate links to the specified resource. The "src" attribute contains a URL containing one or more of the following fields, into which are substituted the appropriate data.

FieldApplicable typesContentsExample
searchTermscharacter, word, stringOne or more Unicode characters.仁
character.hanyudazidiancharacterThe page number on which a character appears in the Hanyu Da Zidian.107
character.gsrcharacterThe page number on which a character appears in Grammata Serica Recensa.388
textRefbook, chapterThe CTP URN corresponding to a textual object.ctp:analects/xue-er
titlebookThe title of a top-level textual object.韓非子
authority-ctextdataThe identifier corresponding to an entity or date in the Data Wiki.ctext:291374

Installing plugins

Each CTP user has their own personal plugin file, which is an XML file consisting of a list of zero or more CTP plugins. You can view and edit your own plugin file via the Plugins section of the Settings page. Installing a plugin simply means adding it to a user's plugin file.

In order to provide an intuitive user experience for users, a request can be made for a CTP plugin available as an XML file via HTTP to be installed to a user's account by opening a URL in the user's web browser. To request that a user install a particular plugin, first ensure that your plugin code is valid XML, confirms to the CTP plugin format, and is available via HTTP. Then to request that a user installs your plugin, direct the user to a link composed as follows: 

https://ctext.org/account.pl?if=en&installplugin=[Plugin URL]
If you wish the user to return to your website after installing the plugin, you may also pass the additional parameter return, with the value set to the URL you wish them to be redirected to after they have installed the plugin.

A user following the link and who does not have the specified plugin installed will be given the opportunity to install it. If the user already has the specified plugin installed and a return URL is specified, the user will be redirected to that URL.

Please note that, if specified, the return URL must be on the same domain as the referring URL.

JSON API

CTP API functions are primarily intended to be called from client-side JavaScript applications using CORS in conjunction with the Plugin system. Please note that usage restrictions and other terms and conditions apply to all usage of the API.

If you would like to write code using the JSON API, please start by reading the documentation. Please note that as this is a pre-release version, functions, parameters, and response formats may change slightly with future updates.

CTP URNs

CTP URNs are unique identifiers describing textual items such as books or parts of books. The CTP API deals with textual information by exchanging these identifiers. For example, textual plugins pass a URN to an external website or tool to uniquely identify the textual item that a user wishes to manipulate; this URN can then be passed to JSON API functions to obtain textual data and metadata about the text. API users must treat these as opaque identifiers and must not attempt to parse them in any way, as new identifiers will be created in the future that may be dissimilar to current URNs.

Some examples of CTP URNs are:

As shown in these examples, you can easily transform a CTP URN into a direct link to the corresponding text by linking directly to the getlink API function with "redirect" set to 1. To obtain the URN corresponding to a https://ctext.org URL programmatically, use the readlink API function.

Textual data response format

Textual data is obtained by passing a CTP URN to the gettext function. This function returns one or more of the following three elements:

Requests for chapters of text, e.g. ctp:analects/xue-er, will return a fulltext element, while requests for larger works or parts of larger works, e.g. ctp:analects, will typically return a subsections element if the client is authenticated, or ERR_REQUIRES_AUTHENTICATION if not.

If a client application is designed to handle only the "fulltext" element, it should use the "chapter" pluginType only; if it can handle both "fulltext" and "subsections", it should use a pluginType of "book,chapter".

Error handling

If an API request cannot be fulfilled, an "error" object is returned in place of the normal response body. This object contains the following fields:

FieldContent
codea constant (see table below) describing the type of error and which does not vary with user interface selection or other factors
descriptionhuman readable description of the error in html (which may include links to help pages or resolution methods)

Applications should use the "code" field to handle application-specific responses, and display the html-formatted "description" field to the end user where necessary - this is particularly recommended in the case of errors such as ERR_REQUEST_LIMIT that may require end user action to resolve.

Possible error codes are as follows:

CodeExample text
ERR_NOT_SUPPORTEDNot supported.
ERR_INVALID_URNInvalid URN.
ERR_UNDEFINED_URNResource does not exist.
ERR_MISSING_PARAM______: Missing required parameter '______'.
ERR_REQUEST_LIMITRequest limit reached. Please log in to allow access to more data.
ERR_INVALID_VALUE'______' is not a valid value for parameter '______'.
ERR_INVALID_PARAM______: '______' is not a valid parameter for this function.
ERR_INVALID_FUNCTIONUnknown function.
ERR_INVALID_APIKEYThe apikey parameter was supplied, but the key was invalid or expired.
ERR_GENERIC[Some other error condition.]
ERR_REQUIRES_AUTHENTICATIONThe requested function requires authentication to continue. Please access the API from a registered IP address or supply a valid API key.

Rate limiting

The primary purpose of the CTP API is to allow the creation of client-side applications which extend CTP functionality in innovative ways, and to allow offline use of reasonable amounts of textual data. All users are welcome to make use of the API; however the frequency of API requests for textual data is limited according to user group:

To determine the current status of a user, use the getstatus function.

Client libraries

A series of tutorials using this module, aimed primarily at newcomers to Python, is available on the Digital Sinology site.

JavaScript access

JavaScript clients can access the API using the Cross-Origin Resource Sharing (CORS) mechanism. In order to allow the API server to grant additional access privileges to logged in users, it is recommended that you set the "withCredentials" property of the XMLHttpRequest object to "true" before making your request. For instance: 

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://api.ctext.org/getstatus', true);
xhr.withCredentials = true;
xhr.send(null);