The JavaScript API

What can I learn from this guide?

Common objects in the JS API

Each page will include four object in the visual namespace: site (information about the site), page (information about the page currently being visited), clientuser (information about the current user), pageuser (information about the user 'owning' the page being visited -- i.e. information about user 'kenny' when visiting /user/kenny or /user/kenny/photo/123.

These properties will be available in each object when applicable. Note for example that visual.clientuser.user_id or visual.pageuser.user_id can be 0 in which case other properties may not be available.

object name properties
visual.site .product_key, .view, .license_id, .user_count, .domain, .site_id, .product_name, .company_url, .custom_logo_p, .site_name, .product_grade, .theme_font, .theme_color, .allow_signup_p, .company_address, .site_key, .company_name
visual.page .url, .view_params, .domain, .name, .title, .return_url, .user_id
visual.clientuser .site_id, .site_admin_p, .username, .user_id, .display_name, .url, .about_abstract
visual.pageuser .site_id, .site_admin_p, .username, .user_id, .display_name, .url, .about_abstract

Additional JS API objects

Depending on the page being visited you may have access to additional JS objects such as:

object name object content and availability
visual.photo the photo being visited on pages suchs as /photo/123; one photo object
visual.photos an array of photo objects; one for each photo in the given view
visual.album one album object
visual.albums array of album objects; one for each album in the given view
visual.comments array of comment objects
visual.tag one tag object
visual.tags an array of tag objects; one for each tag in the given view
visual.user one user object
visual.users an array of user objects; one for each tag in the given view

Note that any singular object such as visual.photo and visual.album may
a) contain more properties that is the case for multiple objects such as items in visual.photos. For example visual.photo contains exif details; visual.photos does not.
b) will also be reference from visual.photos[0] or ...

Using the JavaScript API from external sites

All these objects are available within the html served in the application, but it's also accessible on demand via the JavaScript API endpoints:

parameter name accepted parameters
/js/users user_id
/js/photos photo_id, user_id, tag, tag_mode, album_id, search, year, month, day, video_p, video_encoded_p
/js/comments comment_id, object_user_id, comment_user_id, replies_to_user_id
/js/albums user_id, album_id
/js/tags tag, user_id
/js/tags/related tag

Each listing is unlikely to include all objects, and you may need to handle pagination. This is done using these addition parameters in requests:

parameter name parameter description
size how many object should be included? Defaults may vary.
p which page in the pagination are we selecting? Defaults to "1".
The values for 'p' and 'size' will be available with the request as visual.p and visual.size

In addition to the request object(s) each API request will include the four basic objects (site, page, clientuser and pageuser) within the visual namespace.

Performing a request might be done like this: 


<script src="http://mydomain.visualblog.net/js/photos?search=summer"></script>
<script>
if (visual.photos.length) alert(visual.photos[0].photo_id);
else alert('no summer photos');
</script>

Requesting only one object from the endpoint (i.e. /js/photos?photo_id=123) may result in more data about the object. In the case of one photo, for example, the returned information includes exif data, which is not available when requesting multiple photos. This is done for performance reasons. (See more information above)

The video_p and video_encoded_p

parameters to /js/photos are worth noting. Basically, setting video_p=0 leaves out videos and vice versa. Setting, video_p=1&video_encoded_p=0 gives you a list of all uploaded video that are not ready to be played yet.

Using API callbacks or getting raw JSON data

In some cases, the approach of setting a visual object may not be exactly what you need in your application. The JavaScript API provides you with two different ways if getting data: Through a callback or through raw data.

Using callback functions is done by adding the parameter callback=myFunction to your API request. In that case, the visual object is sent directly to the function myFunction when the data becomes ready:

Performing a request might be done like this: 


<script>
function myFunction(visual) {
  if (visual.photos.length) alert(visual.photos[0].photo_id);
  else alert('no summer photos');
}
</script>
<script src="http://mydomain.visualblog.net/js/photos?callback=myFunction&search=summer"></script>

Relatedly, you can get the visual object as a raw JSON by using the parameter raw=t. This allows you a greater level of control of when the object is loaded by using AJAX:

For example, using Prototype to form your request, you'd do something like this: 


<script>
function buildSlideshowOfPhotos(photos) {
  ... write ingenious code here ...
}
function showSlideshow(tag) {
  new Ajax.Request('http://myvisualblog.com/js/photos', {method:'POST', postBody:'raw=t&tag='+encodeURI(tag), onComplete:function(r) {
		       var visual = eval('(' + r.responseText + ')');
		       buildSlideshowOfPhotos(visual.photos);
		     }}
		   );
}
</script>
<input type="button" onclick="showSlideshow('summer');" value="Show summer photos"/>

(Obviously, this will only work with liberal security settings in your browser, which renders the example ... well, only an example.)