API Endpoints
Below is a list of endpoints available through the Creators GET API service.
Standard parameters
Each API endpoint has a set of common parameters: the format option at the beginning of the URL, and limit and offset at the end:
/api/controller/function/format/{params}/limit/offset
Format options
- xml — return results in a generic XML container
- json — return results in JSON format
- txt — return results in plain text (tab delimited) format
- csv — return results in Comma Separated Values (CSV) format. Common for Excel viewing and manipulation.
Limit and Offset
Each request can be followed by a limit and an offset parameter. Limit will limit the number of rows returned (default 10) and offset will offset the beginning of the results from the head of the result stack (default 0)
Authentication
Requests to the GET API must be authenticated to your account. There are two methods of doing this:
If you access API endpoints in a browser, you'll be prompted to authenticate with your GET username and password via HTTP Basic auth. This is the more human-friendly option.
If you are using the API to build your own programs, you may authenticate by passing your account's API key (found in your settings) in an HTTP header titled X_API_KEY.
Features
Functions to get feature information, feature and release lists.
/get_list/format/{file_code}/limit/offset
Gets a list of active features or releases.
Params
{file_code}— Unique code associated with a feature. Default NULL?start_date— Date to begin a date range filter. Optional, specified by a GET parameter. Format is YYYY-MM-DD.?end_date— Date to end a date range filter. Format: YYYY-MM-DD.?get_all— Return a full list of features, including inactive ones.?web— Return several fields handy for web publishing
Return values
If {file_code} is omitted or set to NULL, returns a list of features you have access to.
If {file_code} is supplied and valid, returns a list of recent releases for that feature.
Examples
/api/features/get_list/json
Result:
[
{
"file_code": "zzi",
"category": "Lifestyle",
"title": "Classic Zig Ziglar",
"type": "Inspiration",
"image": None,
"thumbnail": None
},
...
]
/api/features/get_list/json/zzi
Result:
[
{
"id": "107117",
"title": "Big Brother Is Watching",
"file_code": "zzi",
"release_date": "2014-05-27 21:00:00",
"byline": "Zig Ziglar",
"preview_text": "...",
"full_text": "...",
"preview_image": None,
"files":
[
{
"url": "/api/files/download/249310",
"sha1": "35b3f1366da8e4805f95097338ced92225601dc0",
"description": "HTML File",
"filename": "zzi052814.html"
},
...
],
"notes":
[
{
"note": "...",
"timestamp": "2014-05-30 12:12:19",
"type": "note"
},
...
],
// ?web=true for the following fields
"permalink": "https://www.creators.com/read/...",
"html_text": "HTML formatted column text",
"web_files": [
"https://cdn.creators.com/...",
]
}
]
/details/format/{file_code}
Get detailed information about a feature.
Params
{file_code}— Unique file code associated with a feature.
Return value
returns a set of data regarding the specified feature including a description and author biography. Square thumbnails are provided if they are available.
Example
/api/features/details/json/zzi
Result:
{
"file_code": "zzi",
"title": "Classic Zig Ziglar",
"category": "Lifestyle",
"image": None,
"thumbnail": None,
"type": "Inspiration",
"authors":
[
{
"name": "Zig Ziglar",
"mugshot": "https://cdn.creators.com/mugshots/zig-ziglar.jpg",
"mugshot_thumb": "https://cdn.creators.com/mugshots/zig-ziglar_thumb.jpg",
"bio": "..."
}
]
}
Files
Functions to get files.
/download/{file_id}
Download a file
Params
{file_id}— Unique ID associated with a file. Obtained through /features/get_list
Return value
Starts a download of the file requested. Note: Request will be redirected to Amazon S3 servers at https://s3.amazonaws.com/ with an HTTP 302
Example
/api/files/download/12345
Result:
/zip/{release_id}
Download a release zip
Params
{release_id}— Unique ID associated with a release. Obtained through /features/get_list
Return value
Starts a download of the file requested. Note: ZIP files are generated on the fly if a cached copy is not present. This can be time consuming for large releases.
Need more?
The GET API provides very limited functionality at the moment. If you are interested in developing an application using our API, please contact us for help getting the data you need.
API Libraries
To make the process of using the GET API a little easier, we have released some API libraries in several programming languages. Our API libs will be updated as the API itself is expanded.
- creators_py — A python GET API interface.
- creators_php — A PHP GET API interface.
Changelog
v0.3.2 [2015-04-01]
Adds support for pycURL to creators_py for non-Unix machines
v0.3.1 [2014-11-04]
Adds get_all option to get_features
v0.3 [2014-10-14]
Adds authenticate function to allow users to log in without pre-knowledge of their API key
v0.2 [2014-10-09]
Adds /files/zip function, and optional header return
Example applications
View By Week
Provides a stripped-down, minimal page-load user experience similar to Creators' original download site. Based solely on API calls.
Live demo: http://get.creators.com/hosted/view_by_week/login
Wordpress RSS Reader
A Wordpress plugin that integrates syndicated content from Creators into a Wordpress site.
Installation
To install, extract the release version of the plugin to wp-content/plugins.
Once the plugin is installed, activate it in the Wordpress dashboard. After activation, go to Creators RSS Reader under settings and configure the plugin with your API key (found in your settings)
Once your API key is set up, the settings page will populate with the features you have access to. Check the box next to a feature to enable it on your site.
Notes
Enabling features in this plugin will create user accounts and post content to your site. If this is not how you want to post content, consider using a generic RSS feed reader plugin instead.
Support
Please use the tech support portal for support and feature requests for this plugin.