Watch the Songbirds Event Livestream Replay
skip

Query API 2.0 (beta)

The Query API is how you get data from a ccHost site installation. This information can used as widgets in a blog or other web page, a feed or raw data for programmatic manipulation.

Parameter Passing

No matter what the calling context, the information in the results and how they are formatted are controlled by setting up parameters and values using the URL query parameter syntax:

name=value&another_name=another_value

For example, to return uploads that have been tagged with either foo or bar you would say:

tags=foo+bar&type=any

To see the results in a RSS feed format, you would add the rss value as a format (f for short) parameter:

tags=foo+bar&type=any&f=rss

Unlike the RSS format which has a pre-defined output format, the HTML format can be further controlled by specifying a template (t for short) to be used. For example, to embed the same results into a web page with links and attribution:

tags=foo+bar&type=any&format=html&t=links_by

See the parameter reference for a detailed explanation of what parameters are available.

Calling Context

The Query API can invoked from several contexts:

  • Remotely via a URL
  • Directly from PHP in a ccHost installation
  • Embedded in a template in a ccHost installation
  • Embedded into a topic using ccHost formatting
  • Embedded into ccHost navigation tabs

URL Remote invocation

The base URL for the Query API is http://example.com/api/query where 'example.com' is the base of the ccHost site installation. Parameters and values are passed URL query parameters. In the following example the user (u for short) is used to limit the results to uploads by a specific uploader:

This type of query request can be used anywhere an URL is used, however only certain formats make sense in some URL contexts. For example, when typing in an URL in your browser, only the f=page is useful. When embedding into a blog use f=html or if used in the SRC parameter of a <script> then f=docwrite should be used.

Directly from PHP

Developers that write extensions to ccHost use the URL query syntax to call the CCQuery object:

require_once('cchost_lib/cc-query.php'); $query = new CCQuery(); $args = $query->ProcessAdminArgs('tags=hip_hop&sort=name&user=teru'); $query->Query($args);

In order to facilitate using query parameters passed to a URL other than api/query, either via GET or POST:

require_once('cchost_lib/cc-query.php'); $query = new CCQuery(); $args = $query->ProcessUriArgs(); $query->Query($args);

Instead of outputting the results into the page directly, the results can be returned as a PHP array by using f=php. The following is an example of using a dataview to retrieve the upload_ids of all uploads by teru tagged as hip_hop

require_once('cchost_lib/cc-query.php'); $query = new CCQuery(); $args = $query->ProcessAdminArgs('tags=hip_hop&u=teru&dataview=ids&b=php'); $results = $query->Query($args); foreach( $results[0] as $row ) { $id = $row['upload_id']; //... }

The $results variable now contains an array that contains the results

Embedded in a template in a ccHost installation

Template developers use the URL query sytax but in a more concise way:

%query('tags=hip_hop&t=links_by_ul&limit=5')%

Embedded into a topic using ccHost formatting

Queries can be embedded into topic content posts in a ccHost site using the following syntax:

[query=template=mplayer&playlist=340][/query]

Embedded into ccHost navigation tabs

ccHost site admins can embed queries into the navigation tabs by selecting 'Query' for the tab type and entering the query. Format is always page.

Concepts and Definitions

Formats

Every query must have a format parameter (or f for short).

The f parameter determines how the final data is returned. There are several categories:

CategoryFormat Values
HTML page, html
Feeds/XML atom, rss, xspf, xml
Javascript js, json, docwrite
Plain text csv, textfile
Special m3u, ids, count

The default format is page which will embed the results into a full HTML page based on the current skin of the ccHost installation. For HTML without the full page use format=html

Templates

For the HTML formats page and html there are many different specialized templates that return the requested in specific HTML snippets.

See the Templates Appendix for details.

Data Views

For non HTML queries a dataview is used to return rows of data. The dataview acts as a column selector while the other query parameters (such as tags and user) determine which rows to return and sort will determine the order.

See the Dataview Appendix section for a list of dataview values in the system.

Specifying Parameters

Use parameters to select which records, how many of them and in which order.

For example in order to return the 10 latest uploads that are tagged as sample with an Attribution license we use the follow query:

Usage Cookbook

Combining Parameters That Make Sense

When queries for a set of uploads it might be helpful to group the parameters so the results are not too limited. For example you probably never want to combine the following parameters: collab, ids, playlist, remixes, remixesof, and sources because they each return a very small set of records.

But things get interesting when you refine the results with some set parameters like lic, reccby, remixmax, remixmin, reqtags, score, sinceu, sinced, tags, or user.

Suppose that you know of a playlist (986) and you want to know which songs are available under an Attribution license:

You want to know of a cappellas by calendargirl that have been remixed less than 5 times...

Example Queries

The lastest 15 uploads sorted by user's full name f=html&t=links_by&limit=15&chop=0&sort=fullname
The latest 15 modified uploads f=html&t=links_by&limit=15&chop=0&sort=last_edit
Playlists created in the last 3 weeks that have at least 3 items t=playlist_2_browse&since=3 weeks ago&minitems=3
Playlists created by user 'teru' sorted alphabetically t=playlist_2_browse&u=teru&sort=name&ord=asc
Uploads sorted by number of playlists they are included in t=playlist_2_uploads&sort=num_playlists&ord=desc
Uploads by user 'teru' ordered by times included in playlists t=playlist_2_uploads&sort=num_playlists&ord=desc&u=teru
Raw header information about a playlier f=html&t=playlist_2_info&ids=1651
Link to the latest 5 topics on the page 'Featured Samples' f=html&t=topic_page_links&limit=5&page=featured-samples
Avatar for the user 'mcjackinthebox' f=html&t=avatar&u=mcjackinthebox
XML formatted search results for 'anthony' in user table. f=xml&t=search_users&limit=5&search_type=any&search=anthony
Yahoo! Easy Listener Flash(tm) plugin with uploads that are tagged 'remix' and either 'ambient' or 'chill' f=html&t=easy_listener&limit=10&reqtags=remix&tags=ambient+chill&type=any
Count of uploads during the month of July 2006 sinced=July 2006&befored=Aug 2006&f=count
Highest recommended uploads from 3 weeks ago sinced=3 weeks ago&befored=2 weeks ago&sort=num_scores
XML with basic user info of the last 3 registered users dataview=user_basic&limit=3&f=xml

Appendix A: Parameter Reference

ParameterShort Form Description
beforeu Unix time
befored Date string (see php's strtodate)
chop Several of the embedding HTML templates will "chop" long names to this value.
collab Return files belonging to a given collaboration project. Value is a numeric id of the project.
datasource Set to topics with format=rss to get topics related feeds. (See type parameter.)
dataview (see Data View section)
format f (see Formats section)
ids Comma-separated numeric ids
lic (See License Values)
limit This will tell the QAPI to return "no more than" a certain number of records. Valid values are:

numeric value A paging system can simulated by setting a limit, combined with offset.
page This tells the QAPI to return no more than the number of records shown on a typical page listing. This is the default value for f=page. This is assigned by the site's administrator, typically in the 10-15 range, and can not be surpassed in URL context.
feed This tells the QAPI to return no more than the number of records in a feed listing. This is the default value for any of the feed category of formats (rss, atom, etc.). This is assigned by the site's administrator, typically in the 15-20 range, and can not be surpassed in URL context.
query This tells the QAPI to return no more than the number of records in a feed listing. This is the default value for any of the non feed or page category of formats (html, csv, etc.). This is assigned by the site's administrator, typically in the 100-200 range, and can not be surpassed in URL context.
default This tells the QAPI to use whatever is the admin assigned value for the current context and format. This is the same as leaving out the limit parameter.
match Template specific, for example t=review_upload&match=%upload_id% and t=topic_thread&match=%thread_id%
nosort Used with param ids to honor the order of ids passed in.
offset Combine with limit to page through results.
paging Used with formats page and html to include prev/next buttons. Valid values are on and off

The default for page is on, for html is off
playlist Return records belonging to a specific playlist. Value is the numeric playlist id
rand Set to 1 to return records in a random order
reccby Return records ecommended by a user at the site. Value is the login name of the user.
remixes Request for remixes of a given upload id
remixesof Request for remixes of a given user (value is login name)
remixmax Uploads that have been remixed no more than remixmax times
remixmin Uploads that have been rmeixed no less than remixmin times
reqtags These tags must be included in upload
reviewee Review topics authored by reviewee
score Uploads that have at least score number of ratings
search sSearch for text words or a phrase.
search_type Valid values are match for an exact phrase, any for matches of any of the terms, all for matches of all of the terms.
sinceu Unix time
sinced Date string (see php's strtodate)
sort (See Valid Sorts)
ord Order of score. Valid values are ASC and DESC.
sources Sources of a given remix
tags Return uploads with the tags (separated by '+'). For multiple tags set the type parameter to either all to see records with all tags or any to see records that have any of the tags.
template t (See Templates Appendix)
thread Used with forum related templates to specify the topics associated with a given thread.
title Used with format=page and some feed formats to display a title at the top of the page or XML file.
type When data source is uploads this is a modifier for the tags parameter. When data source is topics this restricts the returning records to topics of that type (e.g. forum, review, artist_qa, etc.) The exact types available are site specific.
user u Return records that were uploaded by a certain user. Value is the login name.

Appendix B: License Values

byAttribution
ncNonCommercial
saShare-Alike
nodNoDerives
byncsaNonCommercial ShareAlike
byncndNonCommercial NoDerives
sSampling
splusSampling+
ncsplusNonCommercial Sampling+
pd Public Domain

Appendix C: Data Views

The following is a list of Data Views.

In order to peek into a Data View use he following query:

f=csv&limit=1&dataview=NAME_OF_DATA_VIEW

replacing NAME_OF_DATA_VIEW with one of the following names:

content_page_blogBlog Content Page
datasource - topics
count
count_pool_itemsdatasource - pool_items
count_ratingsdatasource - ratings
count_tagsdatasource - tags
count_topicsdatasource - topics
defaultdatasource - uploads
files
ids
infoDeep info for upload details
info_avatarDeep info (no remixes, user avatar)
linksdatasource - uploads
links_by
links_by_chop
links_by_dl
links_by_poolUsed by upload listing for Samples are From
datasource - pool_item
links_dl
links_extra
links_short
list_narrowdatasource - uploads
passthruPass Thru (noop)
playlist_detailPlaylist details
datasource - cart
playlist_line
playlist_reorder
playlistsPlaylist line info
datasource - cart
pool_itemdatasource - pool_item
pool_item_history_listUsed by upload histogram
datasource - pool_item
pool_item_listPool Item Listing
datasource - pool_item
pool_item_searchdatasource - pool_item
required_args - match
pool_item_search_gendatasource - pool_item
required_args - match
remixes_of
rss_20For RSS 2.0 Feed
rss_20_topicsFor RSS 2.0 Topic Feed
datasource - topics
search_remixrequired_args - match
search_remix_artistrequired_args - match
search_remix_genrequired_args - match
search_remix_gen_artistrequired_args - match
search_remix_gen_titlerequired_args - match
search_remix_titlerequired_args - match
tag_aliasReturn tag aliases
datasource - tag_alias
require_arg - search
tag_catBasic tag categories
datasource - tag_cat
tagsBasic tags
datasource - tags
tags_with_catTags that only have categories
datasource - tags
topic_infoSimple Topic Info
datasource - topics
topicsGeneric Topics
datasource - topics
upload_column
upload_descriptionUpload Description
datasource - uploads
upload_extra
upload_histogramAll the information needed for upload history
upload_list_wideMultiple upload listing (wide)
datasource - uploads
upload_menu
upload_ownerUpload name, id with owner name, id
upload_pageAll the information needed for uploads page
user_basicBasic user info for data mining
datasource - user

Appendix D: Sort values

Valid sort requests depends on the data source:

Data SourceValueDescription
users fullname Aritst display name
date Registration date
user Artist login name
user_remixes Number of remixes
remixed Number of times remixed
uploads Number of uploads
userscore Artistss average rating
user_num_scores Number of ratings
user_reviews Reviews left by artist
user_reviewed Reviews left for artist
posts Forum topics by artist
uploads Same as user +
name Upload name
lic Upload license
date Upload date
last_edit Upload last edited
remixes Upload's remixes
sources Upload's sources
num_scores Number of ratings
num_playlists Number of playlists
id Internal upload id
local_remixes Upload's local remixes
pool_remixes Upload's remote remixes
local_sources Upload's local sources
pool_sources Upload's sample pool sources
rank Upload Rank
score Upload's ratings
topicsname Topic name
date Topic date
type Topic type
left Topic tree
collab Same as user +
name Collaboration name
date Collaboration creation date
user Collaboration owner (instead of every artist)
pool_items name Pool item name
user Pool item artist

Appendix E: HTML Templates

The templates are grouped by specifc usage scenarios they where designed for.

Formats - Designed for blogs and other off-site pages
big_contactBig Contact Flash Player
linksLinks to upload page
links_ulLinks to upload page (UL)
links_byLinks to upload page with attribution
links_by_dl_ulLinks to upload page with attribution and download links (UL)
links_streamLinks to upload page with attribution and stream links
links_dlLinks to upload page with download links
links_by_ulLinks to uploads with attribution (UL)
links_by_licLinks with license, attribution)
medMedium verbose (license, attribution, download link, tags, description)
links_by_dl_namesNamed download links (good for Y! Music player)
easy_listenerY!(tm) Easy Listener Player
Topic Formats - Designed for blogs and other off-site pages (topics)
topic_page_linksContent topic links (set page=content_page_name)
required_args page
topic_dumpContent topic links (set type=topic_type
datasource topics
required_args type
newsNew blurbs (set type=news
datasource topics
required_args type
topic_links_nextNext-prev Content topic links(set page=content_page_name,topic=topic_name)
required_args page
topicSingle topic [ids = topic]
required_args ids
upload_descriptionSingle upload descrption [ids = upload_id]
required_args ids
topic_replyTopic text for reply form [ids = topic]
required_args ids
Object Embeddings - Object/Flash embeddings
mplayer-buttonFabricio Zuardi's Button Player - Requires Flash
mplayerFabricio Zuardi's Music Player - Requires Flash
mplayerbigFabricio Zuardi's Music Player BIG - Requires Flash
yahoo_blackFabricio Zuardi's Player - (Yahoo Repl.)
Page - Designed to be used within the main site
upload_page_narrowSingle upload page (narrow)
require_args ids
upload_page_wideSingle upload page (wide)
Search Results - Used by site search feature
search_forumsFor forums search results (set type=forum)
example type=forum&t=search_forums&limit=30&search_type=any&s=charlie+rose
datasource topics
required_args type, search
search_playlistsFor playlist search results
example limit=30&search_type=any&search=charlie+rose
datasource cart
required_args search
search_pool_itemsFor pool items search results (set type=pools)
example type=pools&t=search_pool_items&limit=30&search_type=any&s=rooster
datasource pool_items
required_args type, search
search_reviewsFor reviews search results (set type=review)
example type=review&t=search_reviews&limit=30&search_type=any&s=charlie+rose
datasource topics
required_args type, search
search_uploadsFor upload search results
example t=search_uploads&limit=30&search_type=any&s=charlie+rose
valid_args search, search_type
required_args search
search_usersFor user search results
example t=search_users&limit=30&search_type=any&search=charlie+rose
datasource users
required_args search
Ajax - Designed to be used in response to ajax requests
reviewers_recent7 most recent reviewers (for menu)
datasource topics
collab_threadCollab style topic thread (set match=collab_id)
example t=collab_thread&f=html&type=collab&upload=123
datasource topics
valid_args type,match
required_args match
pools_listDisplay remix searchable pools
datasource pools
infoInfo popup for upload
collab_usersList collab users (embedded in collab page)
datasource collab_users
valid_args collab
collab_filesList files in collaboration
valid_args ids, collab
playlist_2_uploadsList playlist lines (Headless playlist with style)
example t=playlist_2_uploads&sort=num_playlists&ord=desc
playable_listListing with Play All/in Window
playlist_2_headPlaylist head (set ids=playlist_id)
required_args ids
playlist_2_infoPlaylist head alt (set ids=playlist_id)
required_args ids
playlist_2_nostylePlaylist head and listing (no styles)
required_args playlist
playlist_2_popup_windowPlaylist in a popop window
required_args playlist
playlists_linksPlaylist links
datasource cart
ajax_menuReturn a menu for an upload
valid_args ids
playlist_2_show_oneShow a playlist (with styles)
required_args playlist
avatarUser avatar
datasource user
require_args user
upload_menuupload_menu
required_args ids
remix_pool_checksused by pool remix search
datasource pool_items
dataview_param ok
remix_checksused by remix search
dataview_param ok